GROFF_FONT(5)                                     GROFF_FONT(5)



NAME
       groff_font - format of groff device and font description
       files

DESCRIPTION
       The groff font format  is  roughly  a  superset  of  the
       ditroff font format.  The font files for device name are
       stored in a directory devname.  There are two  types  of
       file: a device description file called DESC and for each
       font F a font file called  F.   These  are  text  files;
       unlike  the  ditroff font format, there is no associated
       binary format.

   DESC file format
       The DESC file can contain the following types of line as
       shown  below.  Later entries in the file override previ-
       ous values.

       Empty lines are ignored.

       charset
              This line and everything following  in  the  file
              are ignored.  It is allowed for the sake of back-
              wards compatibility.

       family fam
              The default font family is fam.

       fonts n F1 F2 F3 ... Fn
              Fonts F1, ..., Fn are mounted in the  font  posi-
              tions  m+1, ..., m+n  where  m  is  the number of
              styles.  This command may extend over  more  than
              one  line.  A font name of 0 causes no font to be
              mounted on the corresponding font position.

       hor n  The horizontal resolution is n machine units.

       image_generator string
              Needed for grohtml only.  It specifies  the  pro-
              gram  to  generate  PNG  images  from  PostScript
              input.  Under GNU/Linux this is  usually  gs  but
              under  other systems (notably cygwin) it might be
              set to another name.

       paperlength n
              The physical vertical  dimension  of  the  output
              medium  in  machine  units.   This  isn't used by
              troff itself but by output devices.   Deprecated.
              Use papersize instead.

       papersize string
              Select a paper size.  Valid values for string are
              the ISO paper types A0-A7, B0-B7,  C0-C7,  D0-D7,
              DL,   and  the  US  paper  types  letter,  legal,
              tabloid, ledger, statement, executive, com10, and
              monarch.   Case  is not significant for string if
              it holds predefined paper types.   Alternatively,
              string  can  be  a  file  name (e.g. `/etc/paper-
              size'); if the file can be  opened,  groff  reads
              the  first  line  and  tests  for the above paper
              sizes.  Finally, string can  be  a  custom  paper
              size in the format length,width (no spaces before
              and after the comma).  Both length and width must
              have  a  unit  appended; valid values are `i' for
              inches, `c' for centimeters, `p' for points,  and
              `P'  for  picas.  Example: 12c,235p.  An argument
              which starts with a digit is always treated as  a
              custom  paper  format.   papersize  sets both the
              vertical and horizontal dimension of  the  output
              medium.

              More  than  one  argument can be specified; groff
              scans from left to right and uses the first valid
              paper specification.

       paperwidth n
              The  physical  horizontal dimension of the output
              medium in machine units.  Deprecated.  Use paper-
              size  instead.   This  isn't used by troff itself
              but by output devices.

       pass_filenames
              Make troff tell the driver the source  file  name
              being  processed.   This  is  achieved by another
              tcommand: F filename.

       postpro program
              Use program as the postprocessor.

       prepro program
              Call program as a preprocessor.

       print program
              Use program as the spooler program for  printing.
              If  omitted,  the  -l and -L options of groff are
              ignored.

       res n  There are n machine units per inch.

       sizes s1 s2 ... sn 0
              This means that  the  device  has  fonts  at  s1,
              s2, ..., sn  scaled  points.   The  list of sizes
              must be terminated by a 0.  Each si can also be a
              range  of  sizes  m-n.   The list can extend over
              more than one line.

       sizescale n
              The scale factor for  point  sizes.   By  default
              this has a value of 1.  One scaled point is equal
              to one point/n.  The arguments to  the  unitwidth
              and sizes commands are given in scaled points.

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

       tcommand
              This means that the postprocessor can handle  the
              t and u output commands.

       unicode
              Indicate that the output device supports the com-
              plete  Unicode  repertoire.   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.   How-
              ever,  if there are entries in a charset section,
              they either override  the  default  mappings  for
              those  particular  characters or add new mappings
              (normally for composite characters).

              This is used for -Tutf8, -Thtml, and -Txhtml.

       unitwidth n
              Quantities in the font files are given in machine
              units  for  fonts  whose  point  size is n scaled
              points.

       unscaled_charwidths
              Make  the  font  handling  module  always  return
              unscaled  glyph  widths.   Needed for the grohtml
              device.

       use_charnames_in_special
              This command indicates that troff  should  encode
              named glyphs inside special commands.

       vert n The vertical resolution is n machine units.

       The  res,  unitwidth, fonts, and sizes lines are compul-
       sory.  Not all commands in the DESC  file  are  used  by
       troff  itself;  some of the keywords (or even additional
       ones) are used  by  postprocessors  to  store  arbitrary
       information about the device.

       Here a list of obsolete keywords which are recognized by
       groff but completely ignored: spare1,  spare2,  biggest-
       font.

   Font file format
       A font file has two sections; empty lines are ignored in
       both of them.

       The first section is a sequence of lines each containing
       a  sequence  of blank delimited words; the first word in
       the line is a key, and subsequent words give a value for
       that key.

       ligatures lig1 lig2 ... lign [0]
              Glyphs  lig1, lig2, ..., lign are ligatures; pos-
              sible ligatures are ff, fi,  fl,  ffi,  and  ffl.
              For  backwards  compatibility,  the list of liga-
              tures may be terminated with a 0.   The  list  of
              ligatures may not extend over more than one line.

       name F The name of the font is F.

       slant n
              The glyphs of the font have a slant of n degrees.
              (Positive means forward.)

       spacewidth n
              The normal width of a space is n.

       special
              The font is special; this means that when a glyph
              is requested that is not present in  the  current
              font,  it  is  searched  for in any special fonts
              that are mounted.

       Other commands are ignored by troff but may be  used  by
       postprocessors  to store arbitrary information about the
       font in the font file.

       The first section can contain comments which start  with
       the # character and extend to the end of a line.

       The  second section contains one or two subsections.  It
       must contain a charset subsection and it may  also  con-
       tain  a  kernpairs  subsection.   These  subsections can
       appear in any order.  Each subsection starts with a word
       on a line by itself.

       The  word  charset  starts  the charset subsection.  The
       charset line is followed by a sequence of  lines.   Each
       line  gives information for one glyph.  A line comprises
       a number of fields separated by  blanks  or  tabs.   The
       format is

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

       name identifies the glyph: if name is a single  glyph  c
       then  it  corresponds to the groff input character c; if
       it is of the form \c where c is a single character, then
       it  corresponds to the special character \[c]; otherwise
       it corresponds to the groff input character \[name].  If
       it  is  exactly  two  characters xx it can be entered as
       \(xx.  Note that single-letter special characters  can't
       be  accessed  as \c; the only exception is `\-' which is
       identical to `\[-]'.  The name --- is special and  indi-
       cates that the glyph is unnamed; such glyphs can only be
       used by means of the \N escape sequence in troff.

       The type field gives the glyph type:

       1      means the glyph has  a  descender,  for  example,
              `p';

       2      means  the  glyph  has  an ascender, for example,
              `b';

       3      means the  glyph  has  both  an  ascender  and  a
              descender, for example, `('.

       The  code  field  gives the code which the postprocessor
       uses to print the glyph.  The glyph can also be input to
       groff  using  this  code  by  means  of  the  \N  escape
       sequence.  The code can be any integer.   If  it  starts
       with  a  0 it is interpreted as octal; if it starts with
       0x or 0X it is intepreted as  hexadecimal.   Note,  how-
       ever, that the \N escape sequence only accepts a decimal
       integer.

       The entity_name field gives an ASCII string  identifying
       the  glyph  which  the  postprocessor uses to print that
       glyph.  This field is optional and is currently used  by
       grops to build sub-encoding arrays for PS fonts contain-
       ing more than 256 glyphs.  (It has also  been  used  for
       grohtml's  entity  names but for efficiency reasons this
       data is now compiled directly into grohtml.)

       Anything on the line after the encoding  field  or  `--'
       are ignored.

       The  metrics field has the form (in one line; it is bro-
       ken here for the sake of readability):

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

       There  must  not  be any spaces between these subfields.
       Missing subfields are assumed to be  0.   The  subfields
       are  all decimal integers.  Since there is no associated
       binary format, these values are not required to fit into
       a  variable  of  type  char as they are in ditroff.  The
       width subfields 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 base-
       line,  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 lowest point
       below the baseline to which the glyph extends (downwards
       is positive); if a glyph does not extend below above the
       baseline, it should be given a zero depth, rather than a
       negative  depth.   The  italic-correction subfield gives
       the amount of space that should be added after the glyph
       when  it is immediately to be followed by a glyph from a
       roman font.  The left-italic-correction  subfield  gives
       the  amount  of  space  that  should be added before the
       glyph when it is immediately to be preceded by  a  glyph
       from  a  roman font.  The subscript-correction gives the
       amount of space that  should  be  added  after  a  glyph
       before adding a subscript.  This should be less than the
       italic correction.

       A line in the charset section can also have the format

              name "

       This indicates that name is just another  name  for  the
       glyph mentioned in the preceding line.

       The  word  kernpairs starts the kernpairs section.  This
       contains a sequence of lines of the form:

              c1 c2 n

       This means that when glyph c1 appears next to  glyph  c2
       the  space  between them should be increased by n.  Most
       entries in  kernpairs  section  have  a  negative  value
       for n.

FILES
       c:/progra~1/groff/share/groff/1.20/font/devname/DESC
              Device description file for device name.

       c:/progra~1/groff/share/groff/1.20/font/devname/F
              Font file for font F of device name.

SEE ALSO
       groff_out(5), troff(1).



Groff Version 1.20       5 January 2009           GROFF_FONT(5)
