# gropdf

## Name



           gropdf - _groff_ output driver for Portable Document Format
    


## Synopsis



           **gropdf**[**-delsW**] [**-F** _font-directory_] [**-I** _inclusion-directory_]
                  [**-p** _paper-format_] [**-u**[_cmap-file_]] [**-y** _foundry_] [_file_ ...]
    
           **gropdf --help**
    
           **gropdf -v**
    
           **gropdf --version**
    


## Description



           The GNU _roff_ PDF output driver translates the output of _troff_(1)
           into Portable Document Format.  Normally, _gropdf_ is invoked by
           _groff_(1) when the latter is given the “**-T pdf** ” option.  (In this
           installation, **ps** is the default output device.)  Use _groff_ 's **-P**
           option to pass any options shown above to _gropdf_.  If no _file_
           arguments are given, or if _file_ is “-”, _gropdf_ reads the standard
           input stream.  It writes to the standard output stream.
    
           See section “Font installation” below for a guide to installing
           fonts for _gropdf_.
    


## Options



           **--help** displays a usage message, while **-v** and **--version** show
           version information; all exit afterward.
    
           **-d** Include debug information as comments within the PDF.  Also
                  produces an uncompressed PDF.
    
           **-e** Forces _gropdf_ to embed _all_ fonts (even the 14 base PDF
                  fonts).
    
           **-F** _dir_ Prepend directory _dir_ /dev _name_ to the search path for font,
                  and device description files; _name_ is the name of the
                  device, usually **pdf**.
    
           **-I** _dir_ Search the directory _dir_ for files named in **\X'pdf: pdfpic'**
                  device extension commands.  **-I** may be specified more than
                  once; each _dir_ is searched in the given order.  To search
                  the current working directory before others, add “**-I .** ” at
                  the desired place; it is otherwise searched last.
    
           **-l** Orient the document in landscape format.
    
           **-p** _paper-format_
                  Set the physical dimensions of the output medium.  This
                  overrides the **papersize** , **paperlength** , and **paperwidth**
                  directives in the _DESC_ file; it accepts the same arguments
                  as the **papersize** directive.  See _groff_font_(5) for details.
    
           **-s** Append a comment line to end of PDF showing statistics,
                  i.e. number of pages in document.  Ghostscript's **ps2pdf**
                  complains about this line if it is included, but works
                  anyway.
    
           **-u**[_cmap-file_]
                  _gropdf_ normally includes a ToUnicode CMap with any font
                  created using _text.enc_ as the encoding file, this makes it
                  easier to search for words which contain ligatures.  You
                  can include your own CMap by specifying a _cmap-file_ or have
                  no CMap at all by omitting the argument.
    
           **-W** Exit with failure status if font embedding fails.
                  Normally, _gropdf_ issues a warning diagnostic and proceeds.
    
           **-y** _foundry_
                  Set the foundry to use for selecting fonts of the same
                  name.
    


## Usage



           _gropdf_ 's input must be in the format produced by _troff_(1) and
           described in _groff_out_(5).  Further, its device and font
           description files must meet certain requirements.  The device
           **resolution** must be an integer multiple of 72 times **sizescale**.  By
           default, _gropdf_ uses a **resolution** of 72000 and a **sizescale** of
           1000.  A valid paper format is mandatory; see _groff_font_(5).
           While the PDF standard allows several font file formats (like
           TrueType), at present _gropdf_ accepts only the same Type 1 Adobe
           PostScript format as _grops_(1).  Fewer Type 1 fonts are supported
           natively in PDF documents than the standard 35 fonts supported by
           _grops_ and PostScript printers, but all are available since _gropdf_
           automatically embeds any that aren't specified by the PDF
           standard.
    
           _gropdf_ supports _foundries_ that permit multiple providers to supply
           the same _groff_ font names.  _groff_ 's compilation process attempts
           to locate Type 1 fonts on the system, populates a _Foundry_ file
           with their locations, and generates font description files
           corresponding to them.  Font description files can also be added
           after installation.  Each such file must contain a directive
                  **internalname** _psname_
           that maps the _groff_ font name (such as “TR”) to a PostScript name
           (such as “Times-Roman”).  Lines starting with **#** and blank lines
           are ignored.  The code for each character given in the font file
           must correspond to the code in the default encoding for the font.
           This code can be used with the **\N** escape sequence in _troff_ to
           select the character even if it lacks a special character name.
           Every character in the font description must exist in the font
           file, and the widths given in the description must match those
           used in the font file.  See _groff_font_(5).
    
           _gropdf_ can automatically _embed_ any downloadable fonts necessary to
           print the document.  Any fonts thus required must be listed in the
           file _/usr/local/share/groff/1.23.0/font/devpdf/download_ , which
           should comprise lines of the form
                  _foundry font file-name_
           where _foundry_ is the foundry name, or blank for the default
           foundry; _font_ is the PostScript name of the font, and _file-name_ is
           the name of the PFA or PFB font file, and can be a pathname (can
           contain slashes).  Any lines beginning with **#** and blank lines are
           ignored; fields must be separated by tabs (spaces are **not**
           allowed); if _file-name_ is not a pathname, it is sought using the
           same mechanism as that used for font metric files.  The _download_
           file itself is also sought using this mechanism.  Foundry names
           are usually a single character (such as ‘U’ for the URW foundry)
           or empty for the default foundry.  This default uses the same
           fonts as _Ghostscript_ uses when it embeds fonts in a PDF file.
    
           The default stroke and fill colors are black.
    
       **Typefaces**
           Styles called **R** , **I** , **B** , and **BI** mounted at font positions 1 to 4.
           Text fonts are grouped into families **A** , **BM** , **C** , **H** , **HN** , **N** , **P** , and **T** ,
           each having members in each of these styles.
    
                  **AR** AvantGarde-Book
                  **AI** AvantGarde-BookOblique
                  **AB** AvantGarde-Demi
                  **ABI** AvantGarde-DemiOblique
                  **BMR** Bookman-Light
                  **BMI** Bookman-LightItalic
                  **BMB** Bookman-Demi
                  **BMBI** Bookman-DemiItalic
                  **CR** Courier
                  **CI** Courier-Oblique
                  **CB** Courier-Bold
                  **CBI** Courier-BoldOblique
                  **HR** Helvetica
                  **HI** Helvetica-Oblique
                  **HB** Helvetica-Bold
                  **HBI** Helvetica-BoldOblique
                  **HNR** Helvetica-Narrow
                  **HNI** Helvetica-Narrow-Oblique
                  **HNB** Helvetica-Narrow-Bold
                  **HNBI** Helvetica-Narrow-BoldOblique
                  **NR** NewCenturySchlbk-Roman
                  **NI** NewCenturySchlbk-Italic
                  **NB** NewCenturySchlbk-Bold
                  **NBI** NewCenturySchlbk-BoldItalic
                  **PR** Palatino-Roman
                  **PI** Palatino-Italic
                  **PB** Palatino-Bold
                  **PBI** Palatino-BoldItalic
                  **TR** Times-Roman
                  **TI** Times-Italic
                  **TB** Times-Bold
                  **TBI** Times-BoldItalic
    
           Another text font is not a member of a family.
    
                  **ZCMI** ZapfChancery-MediumItalic
    
           Special fonts include **S** , the PostScript Symbol font; **SS** , a subset
           of **S** with slanted lowercase Greek letters; **EURO** , which offers a
           Euro glyph in several styles for use with old devices lacking it;
           and **ZD** , Zapf Dingbats.  In contrast to _grops_ , _gropdf_ does not
           require a reversed variant of it (**ZDR**); the “hand pointing left”
           glyph (**\[lh]**) is available nevertheless, since _pdf.tmac_ defines it
           using the **\X'pdf: xrev'** device extension command (see below).
           Some glyphs in these fonts are unnamed and must be accessed as
           indexed characters, using the **\N** escape sequence.
    
           The fonts corresponding to **EURO** and **SS** are unknown to the PDF
           standard; _groff_ therefore provides their AFM files (font metrics)
           and PFA or PFB files so that they can be used with other software
           and embedded in PDF output.
    
           _gropdf_ furthermore supports a naming scheme for East Asian
           typefaces shared with _grohtml_(1), _grops_(1), and _grotty_(1).
    
                  **CSH** Simplified Chinese, Hei style
                  **CSS** Simplified Chinese, Song style
                  **CTH** Traditional Chinese, Hei style
                  **CTS** Traditional Chinese, Song style
                  **JPG** Japanese, Gothic style
                  **JPM** Japanese, Mincho style
                  **KOG** Korean, Gothic style
                  **KOM** Korean, Mincho style
    
       **Device extension commands**
           _gropdf_ supports many device extensions, accessed with the _groff_
           request **device** or _roff_ **\X** escape sequence.  First, it understands
           many of the device extensions supported by _grops_(1).
    
           **\X'ps: invis'**
                  Suppress output.
    
           **\X'ps: endinvis'**
                  Stop suppressing output.
    
           **\X'ps: exec gsave currentpoint 2 copy translate** _n_ **rotate neg exch**
           **neg exch translate'**
                  where _n_ is the angle of rotation.  This is to support the
                  **align** command in _pic_(1).
    
           **\X'ps: exec grestore'**
                  Used by _pic_(1) to restore state after rotation.
    
           **\X'ps: exec** _n_ **setlinejoin'**
                  where _n_ can be one of the following values.
    
                  0 = Miter join
                  1 = Round join
                  2 = Bevel join
    
           **\X'ps: exec** _n_ **setlinecap'**
                  where _n_ can be one of the following values.
    
                  0 = Butt cap
                  1 = Round cap, and
                  2 = Projecting square cap
    
           **\X'ps:**... **pdfmark'**
                  All the _pdfmark_ macros installed by using _-m pdfmark_ or _-m_
                  _mspdf_ (see documentation in _pdfmark.pdf_).  A subset of
                  these macros are installed automatically when you use **-Tpdf**
                  so you should not need to use “**-m pdfmark** ” to access most
                  PDF functionality.
    
           _gropdf_ also supports a subset of the commands introduced in
           _gpresent_ 's _present.tmac_.
    
                  **PAUSE**
                  **BLOCKS**
                  **BLOCKE**
    
           These allow you to create presentation PDFs.  Many of the other
           commands are already available in other macro packages.
    
           These commands are implemented with _groff_ X commands:-
    
           **\X'ps: exec %%%%PAUSE'**
                  The section before this is treated as a block and is
                  introduced using the current **BLOCK** transition setting (see
                  “**\X'pdf: transition'** ” below).  Equivalently, **.pdfpause** is
                  available as a macro.
    
           **\X'ps: exec %%%%BEGINONCE'**
                  Any text following this command (up to %%%%ENDONCE) is
                  shown only once, the next %%%%PAUSE will remove it.  If
                  producing a non-presentation PDF, i.e. ignoring the pauses,
                  see _GROPDF_NOSLIDE_ below, this text is ignored.
    
           **\X'ps: exec %%%%ENDONCE'**
                  This terminates the block defined by %%%%BEGINONCE.  This
                  pair of commands is what implements the .BLOCKS
                  Once/.BLOCKE commands in _present.tmac_.
    
           The _mom_ macro package already integrates these extensions, so you
           can build slides with _mom_.
    
           If you use _present.tmac_ with _gropdf_ there is no need to run the
           program _presentps_(1) since the output will already be a
           presentation PDF.
    
           All other **ps:** tags are silently ignored.
    
           _gropdf_ also recognizes a device extension used by the DVI driver.
    
           **\X'papersize=**_width_**,**_length_**'**
                  Set the page dimensions in centimeters to _width_ by _length._
                  If the **-l** option was specified, these dimensions are
                  swapped.  Changes to the paper dimensions should occur
                  prior to the first page, or during page ejection before
                  starting a subsequent one.
    
                  _Caution:_ the ordering of dimensions differs from that used
                  by _papersize.tmac_ and _troff_(1)'s “**-d paper** ” option.
    
           _gropdf_ supports several more device extensions using the **pdf:** tag.
           Some have counterpart _convenience macros_ that take the same
           arguments and behave equivalently.
    
           **\X'pdf: pdfpic** _file alignment width height line-length_**'**
                  Place an image from file _file_ of desired _width_ and _height_
                  (if _height_ is missing or zero then it is scaled
                  proportionally).  If _alignment_ is **-L** the drawing is left-
                  aligned.  If it is **-C** or **-R** a _line-length_ greater than the
                  width of the drawing is required as well.  If _width_ is
                  specified as zero then the width is scaled in proportion to
                  the height.  If both _width_ and _height_ are non-zero the
                  image is scaled to ‘best fit’.
    
                  The availability of other software on the system, such as
                  _PerlMagick_ , influences the types of image files _gropdf_ can
                  embed in its output.
    
                 ┌───────┬──────┬─────────┬─────────────┬────────────────────┐
                 │       │ none │ _file_(1) │ _identify_(1) │ _Image::Magick_(3pm) │
                 ├───────┼──────┼─────────┼─────────────┼────────────────────┤
                 │ _.pdf_  │  ✓   │    ✓    │      ✓      │         ✓          │
                 ├───────┼──────┼─────────┼─────────────┼────────────────────┤
                 │ _.jpg_  │  ✗   │    ✓    │      ✓      │         ✓          │
                 ├───────┼──────┼─────────┼─────────────┼────────────────────┤
                 │ _.jp2_  │  ✗   │    ✗    │      ✓      │         ✓          │
                 ├───────┼──────┼─────────┼─────────────┼────────────────────┤
                 │ other │  ✗   │    ✗    │      ✗      │         ✓          │
                 └───────┴──────┴─────────┴─────────────┴────────────────────┘
    
                  See _groff_tmac_(5) for a description of the **PDFPIC** macro,
                  which provides a convenient high-level interface for
                  inclusion of various graphic file formats.
    
           **\X'pdf: xrev'**
                  Toggle the reversal of glyph direction.  This feature works
                  by reversing all following text.  Each separate letter is
                  also mirrored.  One application is the reversal of glyphs
                  in the Zapf Dingbats font.  To restore the normal glyph
                  orientation, repeat the command.
    
           **\X'pdf: markstart** _/ANN-definition_**'**
           **\X'pdf: markend'**
                  Macros that support PDF bookmarks use these calls
                  internally to start and stop (respectively) the placement
                  of the bookmark's _hot spot;_ the user will have called
                  “**.pdfhref L** ” with the text of the hot spot.  Normally,
                  these are never used except from within the _pdfmark_ macros.
    
           **\X'pdf: marksuspend'**
           **\X'pdf: markrestart'**
                  If you use a page location trap to produce a header or
                  footer, or otherwise interrupt a document's text, you need
                  to use these commands if a PDF _hot spot_ crosses a trap
                  boundary; otherwise any text output by the trap will be
                  marked as part of the hot spot.  To prevent this error,
                  place these device extension escape sequences or their
                  corresponding convenience macros **.pdfmarksuspend** and
                  **.pdfmarkrestart** at the start and end of the trap macro,
                  respectively.
    
           **\X'pdf: pagename** _name_**'**
                  Assign the current page a _name_.  All documents bear two
                  default names, ‘**top** ’ and ‘**bottom** ’.  The convenience macro
                  for this command is **.pdfpagename**.
    
           **\X'pdf: switchtopage** _when name_**'**
                  Normally each new page is appended to the end of the
                  document, this command allows following pages to be
                  inserted at a _‘named’_ position within the document (see
                  pagename command above).  _‘when’_ can be either ‘ _after_ ’ or
                  ‘ _before_ ’.  If it is omitted it defaults to ‘ _before_ ’.  It
                  should be used at the end of the page before you want the
                  switch to happen.  This allows pages such as a TOC to be
                  moved to elsewhere in the document, but more esoteric uses
                  are possible.  The convenience macro for this command is
                  **.pdfswitchtopage**.
    
           **\X'pdf: transition** _feature mode duration dimension motion_
           _direction scale bool_**'**
                  where _feature_ can be either SLIDE or BLOCK.  When it is
                  SLIDE the transition is used when a new slide is introduced
                  to the screen, if BLOCK then this transition is used for
                  the individual blocks which make up the slide.
    
                  _mode_ is the transition type between slides:-
    
                         **Split** - Two lines sweep across the screen, revealing
                         the new page.  The lines may be either horizontal or
                         vertical and may move inward from the edges of the
                         page or outward from the center, as specified by the
                         _dimension_ and _motion_ entries, respectively.
                         **Blinds** - Multiple lines, evenly spaced across the
                         screen, synchronously sweep in the same direction to
                         reveal the new page.  The lines may be either
                         horizontal or vertical, as specified by the
                         _dimension_ entry.  Horizontal lines move downward;
                         vertical lines move to the right.
                         **Box** - A rectangular box sweeps inward from the edges
                         of the page or outward from the center, as specified
                         by the _motion_ entry, revealing the new page.
                         **Wipe** - A single line sweeps across the screen from
                         one edge to the other in the direction specified by
                         the _direction_ entry, revealing the new page.
                         **Dissolve** - The old page dissolves gradually to
                         reveal the new one.
                         **Glitter** - As Dissolve, except that the effect sweeps
                         across the page in a wide band moving from one side
                         of the screen to the other in the direction
                         specified by the _direction_ entry.
                         **R** - The new page simply replaces the old one with no
                         special transition effect; the _direction_ entry shall
                         be ignored.
                         **Fly** - (PDF 1.5) Changes are flown out or in (as
                         specified by _motion_), in the direction specified by
                         _direction_ , to or from a location that is offscreen
                         except when _direction_ is **None**.
                         **Push** - (PDF 1.5) The old page slides off the screen
                         while the new page slides in, pushing the old page
                         out in the direction specified by _direction_.
                         **Cover** - (PDF 1.5) The new page slides on to the
                         screen in the direction specified by _direction_ ,
                         covering the old page.
                         **Uncover** - (PDF 1.5) The old page slides off the
                         screen in the direction specified by _direction_ ,
                         uncovering the new page in the direction specified
                         by _direction_.
                         **Fade** - (PDF 1.5) The new page gradually becomes
                         visible through the old one.
    
                  _duration_ is the length of the transition in seconds
                  (default 1).
    
                  _dimension_ (Optional; **Split** and **Blinds** transition styles
                  only) The dimension in which the specified transition
                  effect shall occur: **H** Horizontal, or **V** Vertical.
    
                  _motion_ (Optional; **Split** , **Box** and **Fly** transition styles
                  only) The direction of motion for the specified transition
                  effect: **I** Inward from the edges of the page, or **O** Outward
                  from the center of the page.
    
                  _direction_ (Optional; **Wipe** , **Glitter** , **Fly** , **Cover** , **Uncover** and
                  **Push** transition styles only) The direction in which the
                  specified transition effect shall moves, expressed in
                  degrees counterclockwise starting from a left-to-right
                  direction.  If the value is a number, it shall be one of: **0**
                  = Left to right, **90** = Bottom to top (Wipe only), **180** =
                  Right to left (Wipe only), **270** = Top to bottom, **315** = Top-
                  left to bottom-right (Glitter only) The value can be **None** ,
                  which is relevant only for the **Fly** transition when the
                  value of _scale_ is not 1.0.
    
                  _scale_ (Optional; PDF 1.5; **Fly** transition style only) The
                  starting or ending scale at which the changes shall be
                  drawn.  If _motion_ specifies an inward transition, the scale
                  of the changes drawn shall progress from _scale_ to 1.0 over
                  the course of the transition.  If _motion_ specifies an
                  outward transition, the scale of the changes drawn shall
                  progress from 1.0 to _scale_ over the course of the
                  transition
    
                  _bool_ (Optional; PDF 1.5; **Fly** transition style only) If
                  **true** , the area that shall be flown in is rectangular and
                  opaque.
    
                  This command can be used by calling the macro
                  **.pdftransition** using the parameters described above.  Any
                  of the parameters may be replaced with a "." which
                  signifies the parameter retains its previous value, also
                  any trailing missing parameters are ignored.
    
                  **Note:** not all PDF Readers support any or all these
                  transitions.
    
           **\X'pdf: background** _cmd left top right bottom weight_**'**
           **\X'pdf: background off'**
           **\X'pdf: background footnote** _bottom_**'**
                  produces a background rectangle on the page, where
    
                  _cmd_    is the command, which can be any of “**page** |**fill** |**box** ”
                         in combination.  Thus, “**pagefill** ” would draw a
                         rectangle which covers the whole current page size
                         (in which case the rest of the parameters can be
                         omitted because the box dimensions are taken from
                         the current media size).  “**boxfill** ”, on the other
                         hand, requires the given dimensions to place the
                         box.  Including “**fill** ” in the command paints the
                         rectangle with the current fill colour (as with
                         **\M[]**) and including “**box** ” gives the rectangle a
                         border in the current stroke colour (as with **\m[]**).
    
                         _cmd_ may also be “**off** ” on its own, which terminates
                         drawing the current box.  If you have specified a
                         page colour with “**pagefill** ”, it is always the first
                         box in the stack, and if you specify it again, it
                         replaces the first entry.  Be aware that the
                         “**pagefill** ” box renders the page opaque, so tools
                         that “watermark” PDF pages are unlikely to be
                         successful.  To return the background to
                         transparent, issue an “**off** ” command with no other
                         boxes open.
    
                         Finally, _cmd_ may be “**footnote** ” followed by a new
                         value for _bottom_ , which is used for all open boxes
                         on the current page.  This is to allow room for
                         footnote areas that grow while a page is processed
                         (to accommodate multiple footnotes, for instance).
                         (If the value is negative, it is used as an offset
                         from the bottom of the page.)
    
                  _left_
                  _top_
                  _right_
                  _bottom_ are the coordinates of the box.  The _top_ and _bottom_
                         coordinates are the minimum and maximum for the box,
                         since the actual start of the box is _groff_ 's drawing
                         position when you issue the command, and the bottom
                         of the box is the point where you turn the box
                         “**off** ”.  The top and bottom coordinates are used only
                         if the box drawing extends onto the next page;
                         ordinarily, they would be set to the header and
                         footer margins.
    
                  _weight_ provides the line width for the border if “**box** ” is
                         included in the command.
    
                  The convenience macro for this escape sequence is
                  **.pdfbackground**.  An _sboxes_ macro file is also available;
                  see _groff_tmac_(5).
    
           **\X'pdf: pagenumbering** _type prefix start_**'**
                  Control the page numbering shown in a PDF reader's outline
                  (which also contains bookmarks).  Normally, the page number
                  associated with each bookmark is its sequence number in the
                  file, but this might not match the desired numbering
                  scheme.  A document may bear a cover sheet (which has no
                  page number); front matter (possibly including a table of
                  contents) that uses lowercase roman numerals; the main
                  matter, which uses arabic numerals; and back matter, which
                  may include appendices that are each prefixed with a letter
                  and independently numbered.  Place this command prior to
                  breaking the page to which the new numbering scheme is to
                  apply.  It then persists until changed again.
    
                  _type_   specifies the numbering system to use. It should be
                         one of “**Decimal** ”, “**Roman** ”, “**roman** ”, “**Alpha** ”, or
                         “**alpha** ”.  This parameter may be abbreviated to the
                         first letter, whose lettercase determines that used
                         for the numbers where applicable.  The ordering used
                         by the alphabetic numbering systems is A-Z ... AA-AZ
                         ... ZA-ZZ.  _type_ can also be “**.** ”, which selects no
                         numbering system; you may still provide a _prefix._
    
                  _prefix_ specifies text to precede the page number.  For
                         example, to number the pages of an appendix “A-1”,
                         “A-2”, and so forth, use a _prefix_ of “**A-** ” and a _type_
                         of “**Decimal** ”.
    
                  _start_  determines the page number.  It defaults to 1.
    
                  The convenience macro for this escape sequence is
                  **.pdfpagenumbering**.
    
       **Macros**
           _gropdf_ 's support macros in _pdf.tmac_ define the convenience macros
           described above.  Some features have no direct device extension
           escape sequence counterpart.
    
           **.pdfinfo /**_field content_ ...
                  Define PDF metadata.  _field_ may be one of **Title** , **Author** ,
                  **Subject** , **Keywords** , or another datum supported by the PDF
                  standard or your reader.  _field_ must be prefixed with a
                  slash.
    
       **Importing graphics**
           _gropdf_ supports only the inclusion of other PDF files for inline
           images.  Such a PDF file may, however, contain any of the graphic
           formats supported by the PDF standard, such as JPEG/JFIF, PNG, and
           GIF.  Any application that outputs PDF can thus be used to prepare
           files for embedding in documents processed by _groff_ and _gropdf_.
    
           The PDF file you wish to insert must be a single page and the
           drawing must just fit inside the media size of the PDF file.  In
           _inkscape_(1) or _gimp_(1), for example, make sure the canvas size
           just fits the image.
    
           The PDF parser _gropdf_ implements has not been rigorously tested
           with all applications that produce PDF.  If you find a single-page
           PDF which fails to import properly, try processing it with the
           _pdftk_(1) program.
                  pdftk _existing-file_ output _new-file_
           You may find that _new-file_ imports successfully.
    
       **TrueType and other font formats**
           _gropdf_ does not yet support any font formats besides Adobe Type 1
           (PFA or PFB).
    


## Font installation



           The following is a step-by-step font installation guide for
           _gropdf._
    
           •  Convert your font to something _groff_ understands.  This is a
              PostScript Type 1 font in PFA or PFB format, together with an
              AFM file.  A PFA file begins as follows.
                     %!PS-AdobeFont-1.0:
              A PFB file contains this string as well, preceded by some non-
              printing bytes.  In the following steps, we will consider the
              use of CTAN's BrushScriptX-Italic 
              ⟨https://ctan.org/tex-archive/fonts/brushscr⟩ font in PFA
              format.
    
           •  Convert the AFM file to a _groff_ font description file with the
              _afmtodit_(1) program.  For instance,
                     $ **afmtodit BrushScriptX-Italic.afm text.map BSI**
              converts the Adobe Font Metric file _BrushScriptX-Italic.afm_ to
              the _groff_ font description file _BSI_.
    
              If you have a font family which provides regular upright
              (roman), bold, italic, and bold-italic styles, (where “italic”
              may be “oblique” or “slanted”), we recommend using **R** , **B** , **I** , and
              **BI** , respectively, as suffixes to the _groff_ font family name to
              enable _groff_ 's font family and style selection features.  An
              example is _groff_ 's built-in support for Times: the font family
              name is abbreviated as **T** , and the _groff_ font names are
              therefore **TR** , **TB** , **TI** , and **TBI**.  In our example, however, the
              BrushScriptX font is available in a single style only, italic.
    
           •  Install the _groff_ font description file(s) in a _devpdf_
              subdirectory in the search path that _groff_ uses for device and
              font file descriptions.  See the _GROFF_FONT_PATH_ entry in
              section “Environment” of _troff_(1) for the current value of the
              font search path.  While _groff_ doesn't directly use AFM files,
              it is a good idea to store them alongside its font description
              files.
    
           •  Register fonts in the _devpdf/download_ file so they can be
              located for embedding in PDF files _gropdf_ generates.  Only the
              first _download_ file encountered in the font search path is
              read.  If in doubt, copy the default _download_ file (see section
              “Files” below) to the first directory in the font search path
              and add your fonts there.  The PostScript font name used by
              _gropdf_ is stored in the **internalname** field in the _groff_ font
              description file.  (This name does not necessarily resemble the
              font's file name.)  If the font in our example had originated
              from a foundry named **Z** , we would add the following line to
              _download_.
                     Z→BrushScriptX-Italic→BrushScriptX-Italic.pfa
              A tab character, depicted as →, separates the fields.  The
              default foundry has no name: its field is empty and entries
              corresponding to it start with a tab character, as will the one
              in our example.
    
           •  Test the selection and embedding of the new font.
                     printf "\\f[BSI]Hello, world!\n" | groff -T pdf -P -e >hello.pdf
                     see hello.pdf
    


## Exit status



           0      _gropdf_ successfully produced a PDF document.
    
           1      _gropdf_ experienced a critical error, or could not interpret
                  its arguments.  No PDF was produced, or the document
                  produced will be unusable.
    
           2      _gropdf_ emitted warnings.  The document produced may be
                  usable, but may fail to render as desired.
    


## Environment



           _GROFF_FONT_PATH_
                  A list of directories in which to seek the selected output
                  device's directory of device and font description files.
                  If, in the _download_ file, the font file has been specified
                  with a full path, no directories are searched.  See
                  _troff_(1) and _groff_font_(5).
    
           _GROPDF_NOSLIDE_
                  If set and evaluates to a true value (to Perl), _gropdf_
                  ignores commands specific to presentation PDFs, producing a
                  normal PDF instead.
    
           _SOURCE_DATE_EPOCH_
                  A timestamp (expressed as seconds since the Unix epoch) to
                  use as the output creation timestamp in place of the
                  current time.  The time is converted to human-readable form
                  using Perl's _gmtime()_ function and recorded in a PDF
                  comment.
    
           _TZ_     The time zone to use when converting the current time to
                  human-readable form; see _tzset_(3).  If _SOURCE_DATE_EPOCH_ is
                  used, it is always converted to human-readable form using
                  UTC.
    


## Files



           _/usr/local/share/groff/1.23.0/font/devpdf/DESC_
                  describes the **pdf** output device.
    
           _/usr/local/share/groff/1.23.0/font/devpdf/_ F
                  describes the font known as _F_ on device **pdf**.
    
           _/usr/local/share/groff/1.23.0/font/devpdf/U-_ F
                  describes the font from the URW foundry (versus the Adobe
                  default) known as _F_ on device **pdf**.
    
           _/usr/local/share/groff/1.23.0/font/devpdf/download_
                  lists fonts available for embedding within the PDF document
                  (by analogy to the **ps** device's downloadable font support).
    
           _/usr/local/share/groff/1.23.0/font/devpdf/Foundry_
                  is a data file used by the _groff_ build system to locate
                  PostScript Type 1 fonts.
    
           _/usr/local/share/groff/1.23.0/font/devpdf/symbolsl.afm_
                  provides metrics for the slanted symbol font known to _groff_
                  as **SS**.  These data facilitate use of the font with non-
                  _groff_ software.
    
           _/usr/local/share/groff/1.23.0/font/devpdf/symbolsl.pfb_
                  supplies the slanted symbol font known to _groff_ as **SS**.
    
           _/usr/local/share/groff/1.23.0/font/devpdf/enc/text.enc_
                  describes the encoding scheme used by most PostScript
                  Type 1 fonts; the **encoding** directive of font description
                  files for the **pdf** device refers to it.
    
           _/usr/local/share/groff/1.23.0/font/devpdf/generate/symbolsl.sfd_
                  is the source form of the _symbolsl.pfb_ font, in spline font
                  database (SFD) format.
    
           _/usr/local/share/groff/1.23.0/tmac/pdf.tmac_
                  defines macros for use with the **pdf** output device.  It is
                  automatically loaded by _troffrc_ when the **pdf** output device
                  is selected.
    
           _/usr/local/share/groff/1.23.0/tmac/pdfpic.tmac_
                  defines the **PDFPIC** macro for embedding images in a
                  document; see _groff_tmac_(5).  It is automatically loaded by
                  _troffrc._
    


## Authors



           _gropdf_ was written and is maintained by Deri James ⟨deri@
           chuzzlewit.myzen.co.uk⟩.
    


## See also



           _/usr/local/share/doc/groff-1.23.0/sboxes/msboxes.ms_
           _/usr/local/share/doc/groff-1.23.0/sboxes/msboxes.pdf_
                  “Using PDF boxes with _groff_ and the _ms_ macros”, by Deri
                  James.
    
           _present.tmac_
                  is part of _gpresent_ 
                  ⟨https://bob.diertens.org/corner/useful/gpresent/⟩, a
                  software package by Bob Diertens that works with _groff_ to
                  produce presentations (“foils”, or “slide decks”).
    
           _afmtodit_(1), _groff_(1), _troff_(1), _groff_font_(5), _groff_out_(5)
    


* * *