PLFormatDoc.tex

\input webmac
\font\logo=manfnt % for the METAFONT logo
\def\MF{{\logo METAFONT}}

\M7. A \.{PL} file is a list of entries of the form
$$\.{(PROPERTYNAME VALUE)}$$
where the property name is one of a finite set of names understood by
this program, and the value may itself in turn be a property list.
The idea is best understood by looking at an example, so let's consider
a fragment of the \.{PL} file for a hypothetical font.
$$\vbox{\halign{\.{#}\hfil\cr
(FAMILY NOVA)\cr
(FACE F MIE)\cr
(CODINGSCHEME ASCII)\cr
(DESIGNSIZE D 10)\cr
(DESIGNUNITS D 18)\cr
(COMMENT A COMMENT IS IGNORED)\cr
(COMMENT (EXCEPT THIS ONE ISN'T))\cr
(COMMENT (ACTUALLY IT IS, EVEN THOUGH\cr
\qquad\qquad IT SAYS IT ISN'T))\cr
(FONTDIMEN\cr
\qquad (SLANT R -.25)\cr
\qquad (SPACE D 6)\cr
\qquad (SHRINK D 2)\cr
\qquad (STRETCH D 3)\cr
\qquad (XHEIGHT R 10.55)\cr
\qquad (QUAD D 18)\cr
\qquad )\cr
(LIGTABLE\cr
\qquad (LABEL C f)\cr
\qquad (LIG C i O 200)\cr
\qquad (LIG C f O 201)\cr
\qquad (KRN O 51 R 1.5)\cr
\qquad (STOP)\cr
\qquad (LABEL O 201)\cr
\qquad (LIG C i O 203)\cr
\qquad (STOP)\cr
\qquad )\cr
(CHARACTER C f\cr
\qquad (CHARWD D 6)\cr
\qquad (CHARHT R 13.5)\cr
\qquad (CHARIC R 1.5)\cr
\qquad )\cr}}$$
This example says that the font whose metric information is being described
belongs to the hypothetical
\.{NOVA} family; its face code is medium italic extended;
and the characters appear in ASCII code positions. The design size is 10
points,
and all other sizes in this \.{PL} file are given in units such that 18 units
equals the design size. The font is slanted with a slope of $-.25$ (hence the
letters actually slant backward---perhaps that is why the family name is
\.{NOVA}). The normal space between words is 6 units (i.e., one third of
the 18-unit design size), with glue that shrinks by 2 units or stretches by 3.
The letters for which accents don't need to be raised or lowered are 10.55
units high, and one em equals 18 units.

The example ligature table specifies that the letter \.f followed by \.i
is changed to code \O{200}, while \.f followed by \.f is changed to \O{201};
and
if \.f is followed by the code \O{51} (which is a right parenthesis) an
additional 1.5 units of space should be inserted after the \.f. The character
code \O{201} is changed to \O{203} if it is followed by \.i; thus, the sequence
\.{ffi} leads to code \O{203}, which is presumably where the `ffi' ligature
appears in the font.

Character \.f itself is 6 units wide and 13.5 units tall, in this example.
Its depth is zero (since \.{CHARDP} is not given), and its italic correction
is 1.5 units.

\fi

\M8. The example above illustrates most of the features found in \.{PL} files.
Note that some property names, like \.{FAMILY} or \.{COMMENT}, take a
string as their value; this string continues until the first unmatched
right parenthesis. But most property names, like \.{DESIGNSIZE} and \.{SLANT}
and \.{LABEL}, take a number as their value. This number can be expressed in
a variety of ways, indicated by a prefixed code; \.D stands for decimal,
\.H for hexadecimal, \.O for octal, \.R for real, \.C for character, and
\.F for ``face.'' Other property names, like \.{LIG}, take two numbers as
their value. And still other names, like \.{FONTDIMEN} and \.{LIGTABLE} and
\.{CHARACTER}, have more complicated values that involve property lists.

A property name is supposed to be used only in an appropriate property
list. For example, \.{CHARWD} shouldn't occur on the outer level or
within \.{FONTDIMEN}.

The individual property-and-value pairs in a property list can appear in
any order. For instance, `\.{SHRINK}' precedes `\.{STRETCH}' in the above
example, although the \.{TFM} file always puts the stretch parameter first.
One could even give the information about characters like `\.f' before
specifying the number of units in the design size, or before specifying the
ligature and kerning table. However, the \.{LIGTABLE} itself is an exception
to this rule; the individual elements of the \.{LIGTABLE} property list
can be reordered only to a certain extent without changing the meaning
of that table.

If property-and-value pairs are omitted, a default value is used. For example,
we have already noted that the default for \.{CHARDP} is zero. The default
for {\sl every\/} numeric value is, in fact, zero, unless otherwise stated
below.

If the same property name is used more than once, \.{PLtoTF} will not notice
the discrepancy; it simply uses the final value given. Once again, however, the
\.{LIGTABLE} is an exception to this rule; \.{PLtoTF} will complain if there
is more than one label for some character. And of course many of the
entries in the \.{LIGTABLE} property list have the same property name.

From these rules, you can guess (correctly) that \.{PLtoTF} operates in four
main steps. First it assigns the default values to all properties; then it
scans
through the \.{PL} file, changing property values as new ones are seen; then
it checks the information and corrects any problems; and finally it outputs
the \.{TFM} file.

\fi

\M9. Instead of relying on a hypothetical example, let's consider a complete
grammar for \.{PL} files. At the outer level, the following property names
are valid:

\yskip\hang\.{CHECKSUM} (four-byte value). The value, which should be a
nonnegative integer less than $2^{32}$, is used to identify a particular
version of a font; it should match the check sum value stored with the font
itself. A check sum of zero, which is the default, is used to bypass
check sum testing. If no checksum is specified in the \.{PL} file,
\.{PLtoTF} will compute the checksum that \MF\ would compute from the
same data.

\yskip\hang\.{DESIGNSIZE} (numeric value, default is 10). The value, which
should be a real number in the range $1.0\L\|x<1024$, represents the default
amount by which all quantities will be scaled if the font is not loaded
with an `\.{at}' specification. For example, if one says
`\.{\\font A=cmr10 at 15pt}' in \TeX\ language, the design size in the \.{TFM}
file is ignored and effectively replaced by 15 points; but if one simply
says `\.{\\font A=cmr10}' the stated design size is used. This quantity is
always in units of printer's points.

\yskip\hang\.{DESIGNUNITS} (numeric value, default is 1). The value
should be a positive real number; it says how many units equals the design
size (or the eventual `\.{at}' size, if the font is being scaled). For
example, suppose you have a font that has been digitized with 600 pixels per
em, and the design size is one em; then you could say `\.{(DESIGNUNITS D 600)}'
if you wanted to give all of your measurements in units of pixels.

\yskip\hang\.{CODINGSCHEME} (string value, default is `\.{UNSPECIFIED}').
The string should not contain parentheses, and its length must be less than 40.
It identifies the correspondence between the numeric codes and font characters.
(\TeX\ ignores this information, but other software programs make use of it.)

\yskip\hang\.{FAMILY} (string value, default is `\.{UNSPECIFIED}').
The string should not contain parentheses, and its length must be less than 20.
It identifies the name of the family to which this font belongs, e.g.,
`\.{HELVETICA}'. (\TeX\ ignores this information; but it is needed, for
example, when converting \.{DVI} files to \.{PRESS} files for Xerox
equipment.)

\yskip\hang\.{FACE} (one-byte value). This number, which must lie between
0 and 255 inclusive, is a subsidiary ident\-ifi\-ca\-tion of the font within
its
family. For example, bold italic condensed fonts might have the same family
name
as light roman extended fonts, differing only in their face byte. (\TeX\
ignores this information; but it is needed, for example, when converting
\.{DVI} files to \.{PRESS} files for Xerox equipment.)

\yskip\hang\.{SEVENBITSAFEFLAG} (string value, default is `\.{FALSE}'). The
value should start with either `\.T' (true) or `\.F' (false). If true,
character
codes less than 128 cannot lead to codes of 128 or more via ligatures or
charlists or extensible characters. (\TeX82 ignores this flag, but older
versions of \TeX\ would only accept \.{TFM} files that were seven-bit safe.)
\.{PLtoTF} computes the correct value of this flag and gives an error message
only if a claimed ``true'' value is incorrect.

\yskip\hang\.{HEADER} (a one-byte value followed by a four-byte value).
The one-byte value should be between 18 and a maximum limit that can be
raised or lowered depending on the compile-time setting of \\{max\←header%
\𡤋ytes}.
The four-byte value goes into the header word whose index is the one-byte
value; for example, to set $\\{header}[18]\K1$, one may write
`\.{(HEADER D 18 O 1)}'. This notation is used for header information that
is presently unnamed. (\TeX\ ignores it.)

\yskip\hang\.{FONTDIMEN} (property list value). See below for the names
allowed in this property list.

\yskip\hang\.{LIGTABLE} (property list value). See below for the rules
about this special kind of property list.

\yskip\hang\.{CHARACTER} The value is a one-byte integer followed by
a property list. The integer represents the number of a character that is
present in the font; the property list of a character is defined below.
The default is an empty property list.

\fi

\M10. Numeric property list values can be given in various forms identified by
a prefixed letter.

\yskip\hang\.C denotes an ASCII character, which should be a standard visible
character that is not a parenthesis. The numeric value will therefore be
between \O{41} and \O{176} but not \O{50} or \O{51}.

\yskip\hang\.D denotes a decimal integer, which must be nonnegative and
less than 256. (Use \.R for larger values or for negative values.)

\yskip\hang\.F denotes a three-letter Xerox face code; the admissible codes
are \.{MRR}, \.{MIR}, \.{BRR}, \.{BIR}, \.{LRR}, \.{LIR}, \.{MRC}, \.{MIC},
\.{BRC}, \.{BIC}, \.{LRC}, \.{LIC}, \.{MRE}, \.{MIE}, \.{BRE}, \.{BIE},
\.{LRE}, and \.{LIE}, denoting the integers 0 to 17, respectively.

\yskip\hang\.O denotes an unsigned octal integer, which must be less than
$2^{32}$, i.e., at most `\.{O 37777777777}'.

\yskip\hang\.H denotes an unsigned hexadecimal integer, which must be less than
$2^{32}$, i.e., at most `\.{H FFFFFFFF}'.

\yskip\hang\.R denotes a real number in decimal notation, optionally preceded
by a `\.+' or `\.-' sign, and optionally including a decimal point. The
absolute value must be less than 1024.

\fi

\M11. The property names allowed in a \.{FONTDIMEN} property list correspond to
various \TeX\ parameters, each of which has a (real) numeric value. All
of the parameters except \.{SLANT} are in design-size units. The admissible
names are \.{SLANT}, \.{SPACE}, \.{STRETCH}, \.{SHRINK}, \.{XHEIGHT},
\.{QUAD}, \.{EXTRASPACE}, \.{NUM1}, \.{NUM2}, \.{NUM3}, \.{DENOM1},
\.{DENOM2}, \.{SUP1}, \.{SUP2}, \.{SUP3}, \.{SUB1}, \.{SUB2}, \.{SUPDROP},
\.{SUBDROP}, \.{DELIM1}, \.{DELIM2}, and \.{AXISHEIGHT}, for parameters
1~to~22. The alternate names \.{DEFAULTRULETHICKNESS},
\.{BIGOPSPACING1}, \.{BIGOPSPACING2}, \.{BIGOPSPACING3},
\.{BIGOPSPACING4}, and \.{BIGOPSPACING5}, may also be used for parameters
8 to 13.

The notation `\.{PARAMETER} $n$' provides another way to specify the
$n$th parameter; for example, `\.{(PARAMETER} \.{D 1 R -.25)}' is another way
to specify that the \.{SLANT} is $-0.25$. The value of $n$ must be positive
and less than \\{max\←param\←words}.

\fi

\M12. The elements of a \.{CHARACTER} property list can be of six different
types.

\yskip\hang\.{CHARWD} (real value) denotes the character's width in
design-size units.

\yskip\hang\.{CHARHT} (real value) denotes the character's height in
design-size units.

\yskip\hang\.{CHARDP} (real value) denotes the character's depth in
design-size units.

\yskip\hang\.{CHARIC} (real value) denotes the character's italic correction in
design-size units.

\yskip\hang\.{NEXTLARGER} (one-byte value), specifies the character that
follows the present one in a ``charlist.'' The value must be the number of a
character in the font, and there must be no infinite cycles of supposedly
larger and larger characters.

\yskip\hang\.{VARCHAR} (property list value), specifies an extensible
character.
This option and \.{NEXTLARGER} are mutually exclusive; i.e., they cannot
both be used within the same \.{CHARACTER} list.

\yskip\noindent
The elements of a \.{VARCHAR} property list are either \.{TOP}, \.{MID},
\.{BOT} or \.{REP}; the values are integers, which must be zero or the number
or a character in the font. A zero value for \.{TOP}, \.{MID}, or \.{BOT} means
that the corresponding piece of the extensible character is absent. A nonzero
value, or a \.{REP} value of zero, denotes the character code used to make
up the top, middle, bottom, or replicated piece of an extensible character.

\fi

\M13. A \.{LIGTABLE} property list contains elements of four kinds, specifying
a
program in a simple command language that \TeX\ uses for ligatures and kerns.

\yskip\hang\.{LABEL} (one-byte value) means that the program for the
stated character value starts here. The integer must be the number of a
character in the font; its \.{CHARACTER} property list must not have a
\.{NEXTLARGER} or \.{VARCHAR} field.

\yskip\hang\.{LIG} (two one-byte values). The instruction `\.{(LIG} $c$ $r$\.)'
means, ``If the next character is $c$, then replace both the current character
and $c$ by the character $r$; otherwise go on to the next instruction.''
Character $r$ must be present in the font, but $c$ need not be.

\yskip\hang\.{KRN} (a one-byte value and a real value). The instruction
`\.{(KRN} $c$ $r$\.)' means, ``If the next character is $c$, then insert
a blank space of width $r$ between the current character character and $c$;
otherwise go on to the next intruction.'' The value of $r$, which is in
units of the design size, is often negative. Character code $c$ must exist
in the font.

\yskip\hang\.{STOP} (no value). This instruction ends a ligature/kern program.
It must follow either a \.{LIG} or \.{KRN} instruction, not a \.{LABEL}
or \.{STOP}.

\fi

\M14. In addition to all these possibilities, the property name \.{COMMENT} is
allowed in any property list. Such comments are ignored.

\fi

\bye