Go to the first, previous, next, last section, table of contents.


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 and BZRto

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.

Metafont output at any size

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.

Proofing with Metafont

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.

Type 1 PostScript fonts and BZRto

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 and BZRto

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.

CCC files

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.

CCC 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)

(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.

CCC 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:

`bbheight ( name )'
The height exclusive of blank space above or below the shape of the character name if it exists.
`bbwidth ( name )'
The width exclusive of side bearings of the character name if it exists.
The height of the capital letters, e.g., `H'. See `xheight' for how this is determined.
`depth ( name )'
The depth of the character name.
The design size of the main input BZR font.
The quad width of the font. This value is determined analogously to `xheight', below.
The maximum depth any character in the font descends below the baseline. Again, this is determined analogously to `xheight'.
`height ( name )'
The height of the character name.
Printer's points; 72.27pt = 1in. Since dimensions specified in points are absolute distances, they do not scale when the font size changes.
`width ( name )'
The set width of the character name.
The x-height of the main input font. If a TFM file corresponding to the main BZR file exists and defines this, that value is used; otherwise, the height of a suitable character (e.g., `x') is used if one exists; otherwise, it's zero. BZRto treats the other font-related units of measure in the same way.

If the character name does not exist, an error is given, and the command ignored.

Invoking BZRto

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.

`-concat bzr-name1, bzr-name2, ...'
Concatenate the main input file with the given bzr-names; if a character code exists in more than one of the BZR files, it's the first occurrence that counts. The BZR files can have any design size; the output is normalized to the size of the main input file.
`-ccc-file filename'
Read the CCC file filename (if filename has a suffix) or `filename.ccc' (if it doesn't). Default is to use font-name for filename, but if BZRto does not find the file `font-name.ccc', it does not complain.
`-encoding filename'
Specify the encoding file for the input font, so character names in the CCC files can be matched to character codes. If filename has no suffix, use `filename.enc', otherwise just filename. The default is to guess the encoding from the `codingscheme' string in a TFM file corresponding to the main input file, if such exists.
Print a usage message. See section Common options.
Translate the input to a Metafont program; write to `font-name.mf'. See section Metafont and BZRto.
Synonym for `-metafont'.
`-oblique-angle angle-in-degrees'
Angle in degrees from the vertical by which to slant the shapes; default is zero.
`-output-file filename'
Output to filename (if it has a suffix) or to `filename.font-format' (if it doesn't), where font-format is `mf', `gsf', etc. If you give more than one of the output format options (i.e., `metafont', `pstype1' and `pstype3'), filename cannot have a suffix. The default is font-name with a trailing number removed, so that, for example, an input filename of `cmr10' becomes `cmr'.
`-ps-font-info name1:value1,...'
Assign each value to the corresponding name when outputting a PostScript font (either Type 1 or Type 3). Case is significant in both the names and values. You can specify the following:
The full PostScript name of the font; e.g., Times-BoldItalic. The default is unknown.
The name of the typeface family to which this font belongs; e.g., Times. The default is to use FontName up to the first `-'.
The typographic weight of the font, e.g., 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'.
The angle in degrees by which the font slopes to the right from the vertical. Default is zero. Typical slanted or italic fonts have values between 10--20.
`isFixedPitch:true or false'
Whether or not this font is monospaced. If a TFM file corresponding to the main BZR file exists, and specifies a zero interword stretch and shrink, and a nonzero interword space, the default is true. Otherwise, it's false.
Distance from the baseline for positioning underlines, in units of the character coordinate system. Default is @math{-100}.
Thickness of underlines. Default is 50.
`UniqueID:non-negative integer'
An integer in the range 0 to 16777215 (2^24 - 1) uniquely identifying this font. The default is zero, meaning (for our purposes) not to output any UniqueID. This avoids unlikely-but-possible conflicts with existing fonts.
Identification for the particular version of this font. If a TFM file corresponding to the main BZR file exists, and specifies a version number, that is the default; otherwise, there is none.
All values except FontName and UniqueID go in the FontInfo dictionary.
Translate the input to (unencrypted) PostScript Type 1 font format; write to `font-name.gsf'. See section Type 1 PostScript fonts and BZRto.
Translate the input to PostScript Type 3 font format; write to `font-name.pf3'. See section Type 3 PostScript fonts and BZRto.
`-range char1-char2'
Only process characters between the character codes char1 and char2, inclusive.
Translate the font to a BPL file, i.e., human-readable text; write to standard output. See section BPL files.
Output progress reports to standard output, unless `-text' is specified, in which case output to standard error.
Print the version number.

BZR files

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.

BZR format introduction

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.

BZR preamble

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

BZR characters consist of an identifying command, metric information, shape information, and a terminating EOC command.

We describe these parts below.

BZR character beginnings

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:

llx[2] lly[2] urx[2] ury[2]

The long form:

BOC @cmindex BOC
llx[3] lly[3] urx[3] ury[3]

Here is a description of these components:

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.

BZR character shapes

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 files

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 files
c1x[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.

BZR postamble

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 files
llx[3] lly[3] urx[3] ury[3]
character locators (see below)
POST_POST @cmindex POST_POST opcode in BZR files
1 to any number of NO_OP's

Here is a description of these components:

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.

Go to the first, previous, next, last section, table of contents.