path: root/man/groff_font.5.man

.TH groff_font @MAN5EXT@ "@MDATE@" "groff @VERSION@"
.SH Name
groff_font \- GNU roff device and font description files
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
.\"
.\" This file is part of groff (GNU roff), which is a free software
.\" project.
.\"
.\" You can redistribute it and/or modify it under the terms of the GNU
.\" General Public License as published by the Free Software Foundation,
.\" either version 2 of the License, or (at your option) any later
.\" version.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see
.\" <http://www.gnu.org/licenses/gpl-2.0.html>.
.
.
.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
.do nr *groff_groff_font_5_man_C \n[.cp]
.cp 0
.
.
.\" ====================================================================
.SH Description
.\" ====================================================================
.
.\" BEGIN Keep parallel with groff.texi node "Device and Font Files".
The
.I groff
font and output device description formats are slight
extensions of those used by AT&T device-independent
.IR troff . \" AT&T
.
In distinction to the AT&T implementation,
.I groff
lacks a binary format;
all files are text files.
.
(Plan\~9
.I troff \" Plan 9
has also abandoned the binary format.)
.
The device and font description files for a device
.I name
are stored in a directory called
.IR dev name.
.
The device description file is called
.IR DESC ,
and,
for each
.RI font\~ f
supported by the device,
a font file
.RI called\~\[lq] f \[rq],
where
.IR f \~is
usually an abbreviation of a font's name and/or style.
.
For example,
the
.B ps
(PostScript)
device has
.I groff
font description files for Times roman
.RB ( TR )
and Zapf Chancery Medium italic
.RB ( ZCMI ),
among many others,
while the
.B utf8
device
(for terminal emulators)
has only font descriptions for the roman,
italic,
bold,
and bold-italic styles
.RB ( R ,
.BR I ,
.BR B ,
and
.BR BI ,
respectively).
.
.
.\" ====================================================================
.SH "\f[I]DESC\f[] file format"
.\" ====================================================================
.
The
.I DESC
file contains a series of directives,
one per line.
.
Except for the
.B charset
directive,
which must come last
(if at all),
the order of the lines is not important.
.
Later entries in the file,
however,
override previous values.
.
Comments start with the
.RB \[lq] # \[rq]
character and extend to the end of a line.
.
Empty lines are ignored.
.
.
.TP
.BI family\~ fam
The default font family is
.IR fam .
.
.
.TP
.BI fonts\~ "n F1"\~\c
.RI .\|.\|.\&\~ Fn
Fonts
.IR F1 ", \|.\|.\|.\|, " Fn
are mounted at font positions
.IR m "\|+\|1, \|.\|.\|., " m \|+\| n
where
.I m
is the number of
.B styles
(see below).
.
This directive may extend over more than one line.
.
A font name of
.RB of\~ 0
causes no font to be mounted at the corresponding position.
.
.
.TP
.BI hor\~ n
The horizontal resolution is
.IR n \~basic
units.
.
All horizontal quantities are rounded to multiples of this value.
.
.
.TP
.BI image_generator\~ program
Use
.I program
to generate PNG images from PostScript input.
.
Under GNU/Linux,
this is usually
.IR gs (1),
but under other systems
(notably Cygwin)
it might be set to another name.
.
The
.IR \%grohtml (@MAN1EXT@)
driver uses this directive.
.
.
.TP
.BI paperlength\~ n
The vertical dimension of the physical output medium is
.IR n \~basic
units.
.
Deprecated:
use
.B papersize
instead.
.
.
.TP
.BI papersize\~ format-or-dimension-pair-or-file-name
Set the dimensions of the physical output medium according to the
argument,
which is either
a standard paper format,
a pair of dimensions,
or the name of a plain text file containing either of the foregoing.
.
Recognized paper formats are the ISO and DIN formats
.BR A0 \[en] A7 ,
.BR B0 \[en] B7 ,
.BR C0 \[en] C7 ,
and
.BR D0 \[en] D7 ;
.\" XXX: tmac/papersize.tmac does not support [ABCD]7.
the U.S.\& formats
.BR letter ,
.BR legal ,
.BR tabloid ,
.BR ledger ,
.BR statement ,
and
.BR executive ;
and the envelope formats
.BR com10 ,
.BR monarch ,
and
.BR DL .
.
Case is not significant for the argument if it holds predefined paper
types.
.
.
.IP
Alternatively,
the argument can be a custom paper size in the format
.IB length , width
(with no spaces before or after the comma).
.
Both
.I length
and
.I width
must have a unit appended;
valid units are
.RB \[lq] i \[rq]
for inches,
.RB \[lq] c \[rq]
for centimeters,
.RB \[lq] p \[rq]
for points,
and
.RB \[lq] P \[rq]
for picas.
.
Example:
.RB \[lq] 12c,235p \[rq].
.
An argument that starts with a digit is always treated as a custom paper
format.
.
.
.IP
Finally,
the argument can be a file name
(e.g.,
.IR /etc/papersize );
if the file can be opened,
.I \%@g@troff
reads the first line and attempts to match either of the other forms.
.
No comment syntax is supported.
.
.
.IP
More than one argument can be specified;
.I \%@g@troff
scans from left to right and uses the first valid paper specification.
.
.
.TP
.BI paperwidth\~ n
The horizontal dimension of the physical output medium is
.IR n \~basic
units.
.
Deprecated:
use
.B papersize
instead.
.
.
.TP
.B pass_filenames
Direct
.I \%@g@troff
to emit the name of the source file being processed.
.
This is achieved with the intermediate output command
.RB \[lq] "x F" \[rq].
.
The
.I \%grohtml
driver uses this directive.
.
.
.TP
.BI postpro\~ program
Use
.I program
as the postprocessor.
.
.
.TP
.BI prepro\~ program
Use
.I program
as a preprocessor.
.
Currently,
this keyword is used only when
.I \%@g@troff
is directed to use the
.B html
or
.B xhtml
output devices.
.
.
.TP
.BI print\~  program
Use
.I program
as the spooler program for printing.
.
If omitted,
the
.B \-l
and
.B \-L
options of
.I groff
are ignored.
.
.
.TP
.BI res\~ n
The device has
.I n
basic units per inch.
.
.
.TP
.BI sizes\~ s1\~\c
.RI .\|.\|.\&\~ sn\~\c
.B 0
The device has fonts at
.IR s1 ,
\&.\|.\|.,
.I sn
scaled points
(see below).
.
The list of sizes must be terminated by
.RB a\~ 0 .
.
Each
.I si
can also be a range of sizes
.IR m \[en] n .
.
The list can extend over more than one line.
.
.
.TP
.BI sizescale\~ n
Set the scale factor for point sizes to one divided
.RI by\~ n .
.
The default
.RB is\~ 1 .
.
.
.TP
.BI styles\~ S1\~\c
.RI .\|.\|.\&\~ Sm
The first
.I m
font positions are associated with styles
.IR S1 ,
\&.\|.\|.,
.IR Sm .
.
.
.TP
.B tcommand
The postprocessor can handle the
.B t
.RB and\~ u
intermediate output commands.
.
.
.TP
.B unicode
The output device supports the complete Unicode repertoire.
.
This directive is useful only for devices which produce character
entities instead of glyphs.
.
.
.IP
If
.B unicode
is present,
no
.B charset
section is required in the font description files since the Unicode
handling built into
.I groff
is used.
.
However,
if there are entries in a
.B charset
section,
they either override the default mappings for those particular
characters or add new mappings
(normally for composite characters).
.
.IP
The
.BR utf8 ,
.BR html ,
and
.B xhtml
output devices use this directive.
.
.
.TP
.BI unitwidth\~ n
Quantities in the font description files are in basic units for fonts
whose point size is
.IR n \~scaled
points.
.
.
.TP
.B unscaled_charwidths
Make the font handling module always return unscaled glyph widths.
.
The
.I \%grohtml
driver uses this directive.
.
.
.TP
.B use_charnames_in_special
This directive indicates that
.I \%@g@troff
should encode named glyphs inside special commands.
.
The
.I \%grohtml
driver uses this directive.
.
.
.TP
.BI vert\~ n
The vertical resolution is
.IR n \~basic
units.
.
All vertical quantities are rounded to multiples of this value.
.
.
.TP
.B charset
This line and everything following it in the file are ignored.
.
It is recognized for compatibility with other
.I troff \" generic
implementations.
.
In GNU
.IR troff , \" GNU
character set repertoire is described on a per-font basis.
.
.
.P
.I \%@g@troff
recognizes but ignores the directives
.BR spare1 ,
.BR spare2 ,
and
.BR biggestfont .
.
.
.P
The
.BR res ,
.BR unitwidth ,
.BR fonts ,
and
.B sizes
lines are mandatory.
.
Directives not listed above are ignored by
.I \%@g@troff
but may be used by postprocessors to store arbitrary information about
a device in the
.I DESC
file.
.
.
.\" ====================================================================
.SH "Font description file format"
.\" ====================================================================
.
On typesetting output devices,
each font is typically available at multiple sizes.
.
While paper size measurements in the device description file are in
absolute units,
measurements applicable to fonts must be proportional to the type size.
.
.I groff
achieves this using the precedent set by AT&T device-independent
.IR troff : \" AT&T
one font size is chosen as a norm,
and all others are scaled linearly relative to that basis.
.
The \[lq]unit width\[rq] is the number of basic units per point when the
font is rendered at this nominal size.
.
.
.P
For instance,
.IR groff 's
.B lbp
device uses a
.B unitwidth
of\~800.
.
In its Times roman font
.RB (\[lq] TR \[rq]),
its
.B spacewidth
is\~833;
this is also the width of its comma,
period,
centered period,
and mathematical asterisk,
while its \[lq]M\[rq] is 2963 basic units.
.
Thus,
an \[lq]M\[rq] on the
.B lbp
device is 2,963 basic units wide at a notional type size of 800\~points.
.
(800-point type is not practical for most purposes,
but using it enables the quantities in the font description files to be
expressed as integers.)
.
.
.P
A font description file has two sections.
.
The first is a sequence of directives;
it can contain comments,
which start with the
.RB \[lq] # \[rq]
character and extend to the end of a line.
.
Empty lines are ignored in both sections.
.
.
.TP
.BI name\~ F
The name of the font
.RI is\~ F .
.
.RB \[lq] DESC \[rq]
and
.RB \[lq] 0 \[rq]
are invalid font names.
.
.
.TP
.BI spacewidth\~  n
The width of a normal,
unadjusted space is
.IR n \~basic
units at a type size of
.IR unit-width \~points.
.
.
.P
The directives above are mandatory in the first section;
those below are optional.
.
.
.TP
.BI slant\~ n
The font's glyphs have a slant of
.IR n \~degrees;
a positive
.I n
slants in the direction of text flow.
.
.
.TP
.BI ligatures\~ lig1\~\c
.RI .\|.\|.\&\~ lign\~\c
.RB [ 0 ]
Glyphs
.IR lig1 ,
\&.\|.\|.,
.I lign
are ligatures;
possible ligatures are
.BR ff ,
.BR fi ,
.BR fl ,
.BR ffi ,
and
.BR ffl .
.
For compatibility with other
.I troff
implementations,
the list of ligatures may be terminated with
.RB a\~ 0 .
.
The list of ligatures must not extend over more than one line.
.
.
.TP
.B special
The font is
.IR special :
when a glyph is requested that is not present in the current font,
it is sought in any mounted fonts that bear this property.
.
.
.P
Other directives in this section are ignored by
.IR \%@g@troff ,
but may be used by postprocessors to store arbitrary information about
the font in the file.
.
.
.P
The second section contains one or two subsections.
.
These can appear in either order;
the first one encountered commences the second section.
.
Each starts with a directive on a line by itself.
.
A
.B charset
subsection is mandatory unless the associated
.I DESC
file contains the
.B unicode
directive.
.
Another subsection,
.BR kernpairs ,
is optional.
.
.
.P
The directive
.B charset
starts the character set subsection.
.
(For typesetter devices,
this keyword is a misnomer since it starts a list of glyphs,
not characters.)
.
It precedes a series of glyph descriptions,
one per line.
.
Each such glyph description comprises a set of fields separated by
spaces or tabs and organized as follows.
.
.
.IP
.I name metrics type code
.RI [ entity-name ]
.RB [ \-\-
.IR comment ]
.
.
.P
.I name
identifies the glyph:
if
.I name
is a single
.RI character\~ c ,
it corresponds to the
.I troff \" generic
input
.RI character\~ c .
.
Otherwise,
it must be of the form
.BI \[rs] name
where
.I name
is at least one character;
it then corresponds to the
.I groff
special character escape sequence
.BI \[rs][ name ]\c
\&,
or the one-sixth and one-twelfth unbreakable space escape sequences,
\[rs]| and \[rs]\[ha]
(\[lq]thin\[rq] and \[lq]hair\[rq] spaces,
respectively).
.
A name consisting of three minus signs,
.RB \[lq] \-\-\- \[rq],
indicates that the glyph is unnamed:
such glyphs can only be accessed by means of the
.B \[rs]N
escape sequence in
.IR troff . \" generic; \N is portable
.
A special character named
.RB \[lq] \-\-\- \[rq]
can still be defined using
.B .char
and similar requests.
.
.
.P
The form of the
.I metrics
field is as follows
(on one line;
it may be broken here for the sake of readability).
.
.
.IP
.I width\/\c
.RI [\fB, \:height\/\c
.RI [\fB, \:depth\/\c
.RI [\fB, \:\%italic-correction\/\c
.RI [\fB, \:\%left-italic-correction\/\c
.RI [\fB, \:\%subscript-correction ]]]]]
.
.
.P
There must not be any spaces between these subfields.
.
Missing subfields are assumed to
.RB be\~ 0 .
.
The subfields are all decimal integers.
.
Since there is no associated binary format,
these values are not required to fit into the C language data type
.B char
as they are in AT&T device-independent
.IR troff . \" AT&T
.
The
.I width
subfield gives the width of the glyph.
.
The
.I height
subfield gives the height of the glyph
(upwards is positive);
if a glyph does not extend above the baseline,
it should be given a zero height,
rather than a negative height.
.
The
.I depth
subfield gives the depth of the glyph,
that is,
the distance below the baseline to which the glyph extends
(downwards is positive);
if a glyph does not extend below the baseline,
it should be given a zero depth,
rather than a negative depth.
.
Italic corrections are relevant to glyphs in italic or oblique styles.
.
The
.I italic-correction
is the amount of space that should be added after an oblique glyph to be
followed immediately by an upright glyph.
.
The
.I left-italic-correction
is the amount of space that should be added before an oblique glyph to
be preceded immediately by an upright glyph.
.
The
.I
subscript-correction
is the amount of space that should be added after an oblique glyph to be
followed by a subscript;
it should be less than the italic correction.
.
.
.P
The
.I type
field gives a featural description of the glyph.
.
.
.TP
1
means the glyph has a descender
(for example,
\[lq]p\[rq]);
.
.
.TP
2
means the glyph has an ascender
(for example,
\[lq]b\[rq]);
and
.
.
.TP
3
means the glyph has both an ascender and a descender
(for example,
parentheses in some fonts).
.
.
.P
The
.I code
field gives a numeric identifier that the postprocessor uses to render
the glyph.
.
The glyph can be specified to
.I troff \" generic
using this code by means of the
.B \[rs]N
escape sequence.
.
The code can be any integer
(that is,
any integer parsable by the C standard library's
.IR strtol (3)
function).
.
.
.P
The
.I entity-name
field defines an identifier for the glyph that the postprocessor
uses to print the
.I \%@g@troff
glyph
.IR name .
.
This field is optional;
it was introduced so that the
.I \%grohtml
output driver could encode its character set.
.
For example,
the glyph
.B \[rs][Po]
is represented by
.RB \[lq] &pound; \[rq]
in HTML 4.0.
.
For efficiency,
these data are now compiled directly into
.IR \%grohtml .
.
.I grops
uses the field to build sub-encoding arrays for PostScript fonts
containing more than 256 glyphs.
.
Anything on the line after the
.I entity-name
field or
.RB \[lq] \-\- \[rq]
is ignored.
.
.
.P
A line in the charset section can also have the following format.
.
.
.IP
.IB name\~ \[dq]
.
.
.P
This notation indicates that
.I name
is another name for the glyph mentioned in the preceding line.
.
Such aliases can be chained.
.
.
.P
The word
.B kernpairs
starts the kernpairs section.
.
It contains a sequence of lines formatted as follows.
.
.
.IP
.I c1 c2 n
.
.
.P
The foregoing means that when glyph
.I c1
is typeset immediately before
.IR c2 ,
the space between them should be increased
.RI by\~ n .
.
Most kerning pairs should have a negative value
.RI for\~ n .
.\" END Keep parallel with groff.texi node "Device and Font Files".
.
.
.\" ====================================================================
.SH Files
.\" ====================================================================
.
.TP
.IR @FONTDIR@/dev name /DESC
describes the output device
.IR name .
.
.
.TP
.IR @FONTDIR@/dev name / F
describes the font known to
.I \%@g@troff
.RI as\~ F
on device
.IR name .
.
.
.\" ====================================================================
.SH "See also"
.\" ====================================================================
.
.IR "Groff: The GNU Implementation of troff" ,
by Trent A.\& Fisher and Werner Lemberg,
is the primary
.I groff
manual.
.
You can browse it interactively with \[lq]info groff\[rq].
.
.
.P
\[lq]Troff User's Manual\[rq]
by Joseph F.\& Ossanna,
1976
(revised by Brian W.\& Kernighan,
1992),
AT&T Bell Laboratories Computing Science Techical Report No.\& 54,
widely called simply \[lq]CSTR\~#54\[rq],
documents the language,
device and font description file formats,
and device-independent output format
referred to collectively in
.I groff
documentation as
.RI \[lq]AT&T\~ troff \[rq].
.
.
.P
\[lq]A Typesetter-independent TROFF\[rq]
by Brian W.\& Kernighan,
1982,
AT&T Bell Laboratories Computing Science Techical Report No.\& 97,
provides additional insights into the
device and font description file formats
and device-independent output format.
.
.
.P
Section \[lq]See also\[rq] of
.IR groff (@MAN1EXT@)
lists utilities available for preparing font files in a variety of
formats for use with
.I groff
output drivers.
.
.
.P
.IR groff_out (@MAN5EXT@),
.IR \%@g@troff (@MAN1EXT@),
.IR \%addftinfo (@MAN1EXT@)
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_groff_font_5_man_C]
.do rr *groff_groff_font_5_man_C
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=groff textwidth=72: