BZRto translates an outline font that's in our home-grown BZR outline font format (described below) to some other form: Metafont, Type 1 PostScript, Type 3 PostScript, or BPL.
BPL format is simply a human-readable form of BZR files. See section BPL files. We discuss the other output forms below.
Besides straight format conversion, BZRto can also:
Metafont is a language for specifying graphic shapes, particularly characters in a font of a type, as well as the name of the program which interprets the language. It is commonly used to generate fonts for TeX and related software (TeX and Metafont were developed more-or-less simultaneously by Donald Knuth during the years 1977--1985). See section Archives, for how to obtain the Metafont program.
BZRto generates a Metafont font `foo.mf' from the input file `foo10.bzr' (the `10' being the design size of the input) if you specify the `-metafont' option, as in:
bzrto -metafont foo
Presuming Metafont has been installed properly at your site, you can then make both a TFM and a GF file for foo at a size of 10pt and rasterized for your most common output device with the command:
mf '\mode:=localfont; input foo'
(The single quotes are not seen by Metafont; they just protect the backslash and semicolon from interpretation by your shell.)
The assignment to mode tells Metafont the name of your output
device. localfont should be a synonym for some real output
device, defined when Metafont was installed. The GF file will be named
`foo.dpigf', where dpi is the resolution of the
localfont device.
Given the TFM and GF file, you can now use the font in TeX.
We described above how to get Metafont output at a size of 10pt.
To generate a GF file for a font foo at a different size, assign
to designsize on the command line, as follows:
mf '\mode:=localfont; designsize:=integer; input foo
For example, if localfont corresponds to a 300dpi
device, and you specify `designsize:=6', this command creates
`foo.180gf', i.e., a 40% reduction from
`foo.300gf'.
In some cases, it may be more convenient to specify a magnification
factor than a new point size. (For example, this is the case if you are
enlarging or reducing an entire document by some constant factor, as
with TeX's \magnification command.) You can do this by
assigning to mag:
mf '\mode:=localfont; mag:=real; input foo
By default, mag is 1.0. You can also assign to both mag
and designsize. For example, if you set designsize to 5
and mag to 4, the output will be a 20pt font.
Although the Metafont language allows nonlinear scaling of fonts, so that the 6pt font would not simply be a reduced version of the 10pt font, BZRto cannot take advantage of this sophistication. The reason is that BZR files specify a single set of outlines, and the nonlinear scaling cannot be deduced from that. Perhaps we will extend the programs someday to handle interpolation between outlines of different sizes.
While creating fonts, it is useful to enlarge the character shapes enough to be able to make out small details. This blowing-up process is called proofing. Metafont works together with GFtoDVI, another program created as part of the TeX project, to do this.
You can make two kinds of proofs with Metafont: gray proofs and
smoke proofs. Metafont calls the former proof mode, and
the latter smoke mode. proof mode is the default, so if
you do not assign to mode at all, you get gray proofs. To get
smoke proofs for a font foo, you run Metafont as follows:
mf '\mode:=smoke; input foo'
(See the preceding sections for general information on running
Metafont.) In proof or smoke mode, by default Metafont
will display the characters online as it runs (if you are on a terminal
capable of this, e.g., running under X). If you aren't interested in
seeing this online output, you can say `nodisplays;' on the command
line.
In both kinds of proofs, the font is produced at a very high resolution,
typically thousands of pixels per inch, to minimize (or eliminate)
distortion due to rasterization difficulties. To be more precise, the
resolution is chosen so that the designsize of the font fills
proof_size inches; by default, proof_size is 7, which
works well enough for both letter-size and A4 paper.
In order to calculate this, Metafont must also know the resolution of
the final output device. This is called proof_resolution, and is
300 by default.
You can change the values of proof_size and
proof_resolution on the command line; the actual calculation is
done in `bzrsetup.mf'.
After running Metafont, you will have a GF file, e.g., `foo.2602gf'. You can then make a DVI file you can preview or print with:
gftodvi foo.2602gf
This creates `foo.dvi'. In the DVI output from GFtoDVI, each character in the font has its own page. Some additional information is also present, as follows:
In proof mode, the character shapes are printed in a "gray"
font, and the starting and ending points of each spline (or line) in the
character outline are shown. (Thus, you can see if Limn did a good job
choosing those points.) If you set @math{proofing > 2}, the
control points for each spline will also be shown. If a point would
otherwise overlap with others on the output, an equation is put off to
the right defining where it appears.
In smoke mode, the character shapes are printed in black; if you
put the output on the wall and stand back, you can get an idea of how
the font is coming along. The character is also shown at its true size
off to the right (assuming you have made the font at the true-size
resolution, of course).
You may find that the extra information to the right of the character
("overflow equations" in proof mode; the true-size character in
smoke mode) is being lost off the edge of the page. You can
change where GFtoDVI puts this with the `-overflow-label-offset'
option to GFtoDVI.
See the Metafontbook and the GFtoDVI documentation for more details.
The Type 1 font format, invented by Adobe Systems, Inc., is the most common representation for PostScript fonts. Adobe first published its specification in the book Adobe Type 1 Font Format in 1990. It defines a limited set of operations; general PostScript programs cannot be represented as Type 1 fonts. It also defines hints--ways of improving characters' appearances at low resolution and/or small small sizes--which cannot be represented in PostScript proper.
BZRto generates a Type 1 font `foo.gsf' from the input file `foo10.bzr' (the `10' being the design size of the input) if you specify the `-pstype1' option, as in:
bzrto -pstype1 foo
The file `foo.gsf' consists only of plain text (it's not really "human-readable", since Type 1 format requires encryption of the character outlines).
Although Type 1 format also allows for encryption of the entire font, this is not required, and BZRto does not do it. Some deficient PostScript interpreters do not recognize unencrypted fonts; but Ghostscript, the GNU quasi-PostScript interpreter, has no trouble. We do not know of any utilities for encrypting an unencrypted Type 1 font, but presumably such a program would not be hard to write.
Type 3 PostScript fonts are not defined in a singular format, as are Type 1 fonts (see the previous section). Rather, they are general PostScript programs which happen to meet the PostScript language's (liberal) requirements for being a font. They can therefore be used with any PostScript interpreter.
BZRto generates a Type 3 font `foo.pf3' from an input BZR file `foo.bzr' if you specify the `-pstype3' option, as in:
bzrto -pstype3 foo
We do not know of any conventional extension for Type 3 fonts; we made up `pf3' to stand for "PostScript font Type 3".
The most important part of a Type 3 font is the BuildChar
routine, which does the actual rendering from the character program.
Unlike Type 1 fonts, whose BuildChar routine is built into the
PostScript interpreter, each Type 3 font supplies its own
BuildChar routine.
The Type 3 fonts output by BZRto use a BuildChar routine defined
in a separate file `bzrbuildch.PS' (distributed in the `bzr'
directory). They use the PostScript run command to read that
file; so if you want to download one to a printer (which naturally will
not have access to the file on your computer), you must replace the
run command with the contents of the file. For PostScript
interpreters which run on a host computer, such as Ghostscript, you have
to install `bzrbuildch.PS' in a directory where it will be found,
but you need not modify the fonts.
The CCC (composite character construction) language allows you to define new characters in terms of existing ones. This is useful for building such characters as pre-accented A's (from a piece accent and an `A').
A CCC file consists of a sequence of character definitions, each of which looks like:
define name = statements end
where name is a character name, presumably from the encoding file specified with the `-encoding' option (see section Invoking BZRto). See section Character names, for the details of character names.
We describe the possible statements below.
You may also include comments starting with a `%' character and continuing to the end of the line.
setchar statements
To use an existing character as part of a new character, you can use
either the setchar or setcharbb statement. They both take
a character name in parentheses as their argument, as in:
setchar ( name ) setcharbb ( name )
See section Character names, for the details of character names.
The difference between the two commands lies in their treatment of the
existing character's sidebearings: the setchar command includes
them, and setcharbb does not. setcharbb also removes
any white space above and below the character shapes, as is usually
present in accent characters.
This difference lets you construct characters without worrying about interaction between their side bearings. For example, you could make an `A' with an acute accent centered over the body of the `A' as follows:
define Aacute = setchar (A) hmove -.5 width (A) vmove height (A) setcharbb (acute) end
(See the next section for a description of the hmove and
vmove commands.) Without the setcharbb command, this
definition would be complicated by the side bearings on the acute
character.
move statements
To change the current position in a CCC file, you can use the
hmove or vmove command; as you might expect, the former
moves horizontally and the latter vertically.
Both take a single argument: a dimension, which is an optional
real number followed by a unit of measure. The real number is a
multiplying factor. For example, one of the units is pt
(signifying printer's points, as usual), so the command `hmove 3pt'
moves three points to the right (a pretty small distance).
Here are the possible units of measure:
If the character name does not exist, an error is given, and the command ignored.
This section describes the options that BZRto accepts. See section Command-line options, for general option syntax.
The root of the main input fontname is called font-name below.
Times-BoldItalic.
The default is unknown.
Times. The default is to use FontName up to the first
`-'.
Bold. If
FontName contains one of the strings `Black', `Book',
`Bold', `Demi', `ExtraBold', `Light', `Heavy',
`Regular', `Semibold', or `Ultra', that is the
weight. Otherwise, BZRto uses `Medium'.
true or false'
true.
Otherwise, it's false.
UniqueID. This avoids unlikely-but-possible conflicts
with existing fonts.
FontName and UniqueID go in
the FontInfo dictionary.
This section describes the technical definition of the BZR file format. It is intended for programmers who wish to write other programs which read or write such files. The present distribution includes a subroutine library which can be shared among programs (Limn, BPLtoBZR, and BZRto all use it); new programs can and probably should use the existing library as well. The source code is in the `bzr' directory.
The BZR file format shares the philosophy of the TeX project file formats (DVI, GF, PK, etc.): machine-independence; compactness; and easy interpretation.
BZR files have three parts: a preamble, character definitions, and a postamble. We describe each below, as well as some general considerations.
This section describes some general conventions of the BZR format.
In the following sections, we use the notation name[n] to mean that some constituent name of the BZR file takes up n bytes. If name is all capital letters, it is an opcode, i.e., a command byte, and therefore we give no [n] after name, since all opcodes are a single byte. The numerical value of each opcode is given in the source file `bzr/bzr_opcodes.h'.
Some values in BZR files are "pointers". These values give the location of some other byte in the file. The first byte is numbered 0, the next byte numbered 1, and so on.
Besides commands which actually define the font, the BZR format has a
NO_OP command, which does nothing. Any number of NO_OP's
can occur between the preamble and the character definitions, between
character definitions and commands within characters, between the
character definitions and the postamble, and after the postamble. But
they may not occur within the preamble, the postamble, or between a
command and its parameters.
Besides simple integers, BZR format uses a fixed-point representation of real numbers called a scaled, which is three bytes: two bytes of fraction and one byte of integer. We can get away with such a small range because almost all numbers are scaled by the design size; i.e., in a 10-point font, a designsize-scaled value of 1.0 would represent 10 points (quite a large distance, relatively speaking).
In fact, designsize-scaled numbers are typically less than 1.0, so the BZR format provides for abbreviating such, thus making the font smaller, as detailed in the following sections.
Negative numbers are represented in 2's complement notation, and multibyte values are stored in BigEndian order, regardless of the conventions of the host computer. This makes a BZR font file portable between different architectures.
The preamble of a BZR file has two components, the font's design size
and a comment: designsize[3], k[1],
comment[k].
See section BZR format introduction, for general information about BZR files and for the definition of the types used here.
The designsize is a scaled number in printer's points.
The k-byte long comment typically identifies the
source and creation date of the BZR file.
BZR characters consist of an identifying command, metric
information, shape information, and a terminating EOC command.
We describe these parts below.
BZR format provides two ways to start characters: an abbreviated one, which saves space in common cases, and a longer form which (we hope) will always suffice.
The short form looks like this:
BOC_ABBREV@cmindex BOC_ABBREVcharcode[1]set-width[2]llx[2]lly[2]urx[2]ury[2]
The long form:
BOC@cmindex BOCcharcode[1]set-width[3]llx[3]lly[3]urx[3]ury[3]
Here is a description of these components:
BOC or BOC_ABBREV opcode byte introduces the character.
charcode defines the character code in question.
set-width defines the set width of the character, given as a
design-size scaled, in printer's points.
llx ... ury (which stand for "lower left @math{x}",
"lower left @math{y}", "upper right @math{x}", and "upper right
@math{y}") define the bounding box for this character. The values are
designsize-scaled, in printer's points. The bounding box is not
guaranteed to be the tightest possible, because it is difficult to
compute the exact path of any splines in the character shape (see section BZR character shapes).
As with other formats, the left side bearing is defined by llx,
and the right side bearing by set-width - urx.
See section BZR format introduction, for general information about BZR files and for the definition of the types used here.
In the BZR format, a character shape is defined as a sequence of (non-contiguous) closed paths, i.e., outlines. Each path can contain straight lines and Bezier cubic splines. As a BZR-reading program interprets the character definition, it keeps track of a "current point", which is initially undefined.
Each path--and therefore also the character shape itself--starts with a
path command: PATH, x[3], y[3]. This
finishes off any previous outline and starts a new one, setting the
current point to (x,y). x and y are
designsize-scaled values in printer's points.
After a path command has started an outline, a sequence of zero or more line and/or spline commands, intermixed in any order, follows. (A path command followed by another path command is allowed, but does nothing useful.)
Although the BZR format itself does not require it, for the font to work properly when translated to some other formats, the "outside curves" must be drawn counterclockwise, and the inside ones clockwise.
The BZR format defines both abbreviated and long versions of both straight line and spline commands, as follows.
The abbreviated line command is:
LINE_ABBREV@cmindex LINE_ABBREV opcode in BZR filesex[2]ey[2]
which defines a straight line from the current point to
(ex,ey). ex and ey are designsize-scaled numbers
in points. After drawing the line, the current point is set to
(ex,ey).
The long form of the line command differs only in starting with a
LINE opcode, and the coordinate parameters being three bytes long,
instead of two.
The spline commands are analogous. Here is the abbreviated form:
SPLINE_ABBREV@cmindex SPLINE_ABBREV opcode in BZR filesc1x[2]c1y[2]c2x[2]c2y[2]ex[2]ey[2]
This defines a Bezier spline with initial point the
current point, control points (c1x,c1y) and (c2x,c2y), and
ending point (ex,ey). The current point is then set to
(ex,ey). As with the line commands, the coordinate parameters
are designsize-scaled in units of points.
Also as with the line commands, the long form of the spline command
differs only in starting with a SPLINE opcode and the other
parameters being three bytes long instead of two.
The postamble of a BZR file consists of the following. See section BZR format introduction, for general information about BZR files and for the definition of the types used here.
POST@cmindex POST opcode in BZR filesllx[3]lly[3]urx[3]ury[3] character locators (see below)POST_POST@cmindex POST_POST opcode in BZR filesnchars[1]post-ptr[4]id[1] 1 to any number ofNO_OP's
Here is a description of these components:
llx ... ury are all designsize-scaled
numbers. They define the bounding box for the entire font, which is
simply the smallest box that encloses all the characters. See section BZR character beginnings.
BOC. There are
two forms of character locators: one abbreviates the common case of the
pointer being less than 65536; the other allows for a full four-byte
pointer value.
More precisely, an abbreviated character locator consists of:
CHAR_LOC_ABBREV charcode[1] pointer[2]and a long character locator consists of:
CHAR_LOCcharcode[1]pointer[4]
nchars is the number of characters defined in the BZR file.
post-ptr points to the POST byte.
id identifies the version of BZR format; this is currently 75.
This way of ending BZR files makes it straightforward to process a BZR
file from end to beginning, even though it must of course be written
beginning to end. The BZR-reading program can position itself at the
end of the file, skip over the NO_OP bytes at the end to the
id byte, and then read the pointer to the postamble proper, which
provides enough information to read each character individually. This
eliminates the need to read the entire (potentially large) BZR file into
memory before doing any processing.