Provided by: groff_1.23.0-5_amd64 bug

Name

       groff_font - GNU roff device and font description files

Description

       The  groff font and output device description formats are slight extensions of those used by AT&T device-
       independent troff.  In distinction to the AT&T implementation, groff lacks a binary format; all files are
       text  files.  (Plan 9 troff has also abandoned the binary format.)  The device and font description files
       for a device name are stored in a devname directory.  The device description file is  called  DESC,  and,
       for  each  font  supported  by  the  device,  a  font description file is called f, where f is usually an
       abbreviation of a font's name and/or style.  For example, the  ps  (PostScript)  device  has  groff  font
       description  files  for Times roman (TR) and Zapf Chancery Medium italic (ZCMI), among many others, while
       the utf8 device (for terminal emulators) has only font descriptions for  the  roman,  italic,  bold,  and
       bold-italic styles (R, I, B, and BI, respectively).

       Device  and font description files are read by the formatter, troff, and by output drivers.  The programs
       typically delegate these files' processing to an internal library, libgroff,  ensuring  their  consistent
       interpretation.

DESC file format
       The  DESC  file  contains a series of directives; each begins a line.  Their order is not important, with
       two exceptions: (1) the res directive must precede any papersize directive; and (2) the charset directive
       must come last (if at all).  If a directive name is repeated, later entries in the file override previous
       ones (except that the paper dimensions are computed based on the res directive last seen  when  papersize
       is  encountered).   Spaces and/or tabs separate words and are ignored at line boundaries.  Comments start
       with the “#” character and extend to the end of a line.  Empty lines are ignored.

       family fam
              The default font family is fam.

       fonts n F1 ... Fn
              Fonts F1, ..., Fn are mounted at font positions m+1, ..., m+n where m is the number of styles (see
              below).  This directive may extend over more than one line.  A font name of 0 causes no font to be
              mounted at the corresponding position.

       hor n  The horizontal motion quantum is n basic units.  Horizontal quantities are  rounded  to  multiples
              of n.

       image_generator program
              Use program to generate PNG images from PostScript input.  Under GNU/Linux, this is usually gs(1),
              but under other systems (notably Cygwin) it might be set to another name.  The  grohtml(1)  driver
              uses this directive.

       paperlength n
              The vertical dimension of the output medium is n basic units (deprecated: use papersize instead).

       papersize format-or-dimension-pair-or-file-name ...
              The  dimensions  of the output medium are as 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 A0A7, B0B7, C0C7, and D0D7;
              the U.S. formats letter, legal, tabloid,  ledger,  statement,  and  executive;  and  the  envelope
              formats com10, monarch, and DL.  Matching is performed without regard for lettercase.

              Alternatively,  the  argument  can be a custom paper format length,width (with no spaces before or
              after the comma).  Both length and width must have a  unit  appended;  valid  units  are  “i”  for
              inches, “c” for centimeters, “p” for points, and “P” for picas.  Example: “12c,235p”.  An argument
              that starts with a digit is always treated as a custom paper format.

              Finally, the argument can be a file name (e.g., /etc/papersize); if the file can  be  opened,  the
              first line is read and a match attempted against each other form.  No comment syntax is supported.

              More  than  one  argument  can  be  specified;  each  is scanned in turn and the first valid paper
              specification used.

       paperwidth n
              The horizontal dimension of the  output  medium  is  n  basic  units  (deprecated:  use  papersize
              instead).

       pass_filenames
              Direct  troff  to  emit  the  name  of the source file being processed.  This is achieved with the
              intermediate output command “x F”, which grohtml interprets.

       postpro program
              Use program as the postprocessor.

       prepro program
              Use program as a preprocessor.  The html and xhtml output devices use this directive.

       print program
              Use program as the print spooler.  If omitted, groff's -l and -L options are ignored.

       res n  The device resolution is n basic units per inch.

       sizes s1 ... sn 0
              The device has fonts at s1, ..., sn scaled  points  (see  below).   The  list  of  sizes  must  be
              terminated  by a 0.  Each si can also be a range of sizes mn.  The list can extend over more than
              one line.

       sizescale n
              A typographical point is subdivided into n scaled points.  The default is 1.

       styles S1 ... Sm
              The first m font mounting positions are associated with styles S1, ..., Sm.

       tcommand
              The postprocessor can handle the t and u intermediate output commands.

       unicode
              The output device supports the complete Unicode repertoire.  This directive  is  useful  only  for
              devices which produce character entities instead of glyphs.

              If  unicode  is  present,  no  charset section is required in the font description files since the
              Unicode handling built into groff is used.  However, if there are entries in  a  font  description
              file's  charset section, they either override the default mappings for those particular characters
              or add new mappings (normally for composite characters).

              The utf8, html, and xhtml output devices use this directive.

       unitwidth n
              Quantities in the font description files are in basic units for fonts whose type size is n  scaled
              points.

       unscaled_charwidths
              Make  the  font handling module always return unscaled glyph widths.  The grohtml driver uses this
              directive.

       use_charnames_in_special
              troff should encode named glyphs inside device control commands.  The  grohtml  driver  uses  this
              directive.

       vert n The vertical motion quantum is n basic units.  Vertical quantities are rounded to multiples of n.

       charset
              This  directive  and  the  rest  of the file are ignored.  It is recognized for compatibility with
              other troff implementations.  In GNU troff, character set repertoire is described  on  a  per-font
              basis.

       troff recognizes but ignores the directives spare1, spare2, and biggestfont.

       The  res,  unitwidth,  fonts,  and sizes lines are mandatory.  Directives not listed above are ignored by
       troff but may be used by postprocessors to obtain further information about the device.

Font description file format

       On typesetting output devices,  each  font  is  typically  available  at  multiple  sizes.   While  paper
       measurements  in the device description file are in absolute units, measurements applicable to fonts must
       be proportional to the type size.  groff achieves this using the precedent set by AT&T device-independent
       troff: one font size is chosen as a norm, and all others are scaled linearly relative to that basis.  The
       “unit width” is the number of basic units per point when the font is rendered at this nominal size.

       For instance, groff's lbp device uses a unitwidth of 800.  Its Times roman font (“TR”) has  a  spacewidth
       of  833;  this  is also the width of its comma, period, centered period, and mathematical asterisk, while
       its “M” is 2,963 basic units.  Thus, an “M” on the 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.)

       A font description file has two sections.  The first is a sequence of directives, and is parsed similarly
       to  the  DESC  file described above.  Except for the directive names that begin the second section, their
       ordering is immaterial.  Later directives of the same name override earlier ones,  spaces  and  tabs  are
       handled in the same way, and the same comment syntax is supported.  Empty lines are ignored throughout.

       name F The  name of the font is F.  “DESC” is an invalid font name.  Simple integers are valid, but their
              use is discouraged.  (groff requests and escape sequences interpret  non-negative  font  names  as
              mounting  positions  instead.   Further,  a  font named “0” cannot be automatically mounted by the
              fonts directive of a DESC file.)

       spacewidth n
              The width of an unadjusted inter-word space is n basic units.

       The directives above must appear in the first section; those below are optional.

       slant n
              The font's glyphs have a slant of n degrees; a positive n slants in the direction of text flow.

       ligatures lig1 ... lign [0]
              Glyphs lig1, ..., lign are ligatures; possible ligatures are  ff,  fi,  fl,  ffi,  and  ffl.   For
              compatibility  with other troff implementations, the list of ligatures may be terminated with a 0.
              The list of ligatures must not extend over more than one line.

       special
              The font is 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.

       Other  directives  in  this  section  are  ignored  by troff, but may be used by postprocessors to obtain
       further information about the font.

       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 charset
       subsection is mandatory unless  the  associated  DESC  file  contains  the  unicode  directive.   Another
       subsection, kernpairs, is optional.

       The  directive  charset  starts the character set subsection.  (For typesetter devices, this directive is
       misnamed 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.

              name metrics type code [entity-name] [-- comment]

       name identifies the glyph: if name is a printable character c,  it  corresponds  to  the  troff  ordinary
       character c.  If name is a multi-character sequence not beginning with \, it corresponds to the GNU troff
       special character escape sequence “\[name]”.  A name consisting of three minus  signs,  “---”,  indicates
       that  the  glyph  is  unnamed:  such  glyphs  can be accessed only by the \N escape sequence in troff.  A
       special character named “---” can still be defined using .char  and  similar  requests.   The  name\-”
       defines  the  minus  sign  glyph.  Finally, name can be the horizontal motion escape sequences, \| and \^
       (“thin” and “hair” spaces, respectively), in which case only the width metric described below is applied;
       a font can thus customize the widths of these spaces.

       The form of the metrics field is as follows (on one line; it may be broken here for readability).

              width[,[height[,[depth[,[italic-correction[,[left-italic-correction[,[
              subscript-correction]]]]]]]]]]

       There must not be any spaces, tabs, or newlines  between  these  subfields,  which  are  in  basic  units
       expressed  as decimal integers.  Unspecified subfields default to 0.  Since there is no associated binary
       format, these values are not required to fit into the C language data type  char  as  they  are  in  AT&T
       device-independent troff.

       The  width  subfield  gives  the  width  of the glyph.  The 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 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 italic-correction is the amount of space that should
       be  added  after  an  oblique  glyph  to  be  followed immediately by an upright glyph.  The 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  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.

       For fonts used with typesetting devices, the type field gives a featural description of the glyph: it  is
       a  bit  mask  recording  whether the glyph is an ascender, descender, both, or neither.  When a \w escape
       sequence is interpolated, these values are bitwise or-ed together for each glyph and  stored  in  the  ct
       register.  In font descriptions for terminal devices, all glyphs might have a type of zero, regardless of
       their appearance.

       0      means the glyph lies entirely between the baseline and a horizontal line at the “x-height” of  the
              font, as with “a”, “c”, and “x”;

       1      means the glyph descends below the baseline, like “p”;

       2      means the glyph ascends above the font's x-height, like “A” or “b”); and

       3      means the glyph is both an ascender and a descender—this is true of parentheses in some fonts.

       The code field gives a numeric identifier that the postprocessor uses to render the glyph.  The glyph can
       be specified to troff using this code by means of the \N escape sequence.  The code can  be  any  integer
       (that is, any integer parsable by the C standard library's strtol(3) function).

       The  entity-name field defines an identifier for the glyph that the postprocessor uses to print the troff
       glyph name.  This field is optional; it was introduced so that the grohtml output driver could encode its
       character  set.   For  example, the glyph \[Po] is represented by “£” in HTML 4.0.  For efficiency,
       these data are now compiled directly into grohtml.  grops uses the field to build sub-encoding arrays for
       PostScript  fonts  containing  more than 256 glyphs.  Anything on the line after the entity-name field or
       “--” is ignored.

       A line in the charset section can also have the form
              name "
       identifying name as another name for the glyph mentioned in the preceding  line.   Such  aliases  can  be
       chained.

       The directive kernpairs starts a list of kerning adjustments to be made to adjacent glyph pairs from this
       font.  It contains a sequence of lines formatted as follows.
              g1 g2 n
       The foregoing means that when glyph g1 is typeset immediately before g2, the space between them should be
       increased by n.  Most kerning pairs should have a negative value for n.

Files

       /usr/share/groff/1.23.0/font/devname/DESC
              describes the output device name.

       /usr/share/groff/1.23.0/font/devname/F
              describes the font known as F on device name.

See also

       Groff:  The  GNU  Implementation  of  troff,  by Trent A. Fisher and Werner Lemberg, is the primary groff
       manual.  You can browse it interactively with “info groff”.

       “Troff User's Manual” by Joseph F. Ossanna, 1976  (revised  by  Brian  W.  Kernighan,  1992),  AT&T  Bell
       Laboratories  Computing  Science  Technical Report No. 54, widely called simply “CSTR #54”, documents the
       language, device and font description file formats, and  device-independent  output  format  referred  to
       collectively in groff documentation as “AT&T troff”.

       “A  Typesetter-independent  TROFF”  by Brian W. Kernighan, 1982, AT&T Bell Laboratories Computing Science
       Technical Report No. 97, provides additional insights into the device and font description  file  formats
       and device-independent output format.

       groff(1),  subsection  “Utilities”, lists programs available for describing fonts in a variety of formats
       such that groff output drivers can use them.

       troff(1) documents the default device and font description file search path.

       groff_out(5), addftinfo(1)