gropdf - PDF driver for groff


   gropdf [-delvs] [-F dir] [-p papersize] [-y foundry] [-u [cmapfile]]
          [files ...]

   It is possible to have whitespace between a command line option and its


   gropdf  translates  the  output  of  GNU troff to PDF.  Normally gropdf
   should be invoked by using the groff command with a -Tpdf  option.   If
   no  files  are given, gropdf reads the standard input.  A filename of -
   also causes gropdf to read the standard input.  PDF output  is  written
   to  the  standard  output.   When gropdf is run by groff options can be
   passed to gropdf using groff's -P option.

   See section FONT INSTALLATION below for a guide how  to  install  fonts
   for gropdf.


   -d     Include  debug  information  as  comments  within the PDF.  Also
          produces an uncompressed PDF.

   -e     Force all fonts to be embedded in the PDF.

   -Fdir  Prepend directory dir/devname to the search path for  font,  and
          device  description  files;  name  is  the  name  of the device,
          usually pdf.

   -l     Print the document in landscape format.

          Set physical dimension of output  medium.   This  overrides  the
          papersize,  paperlength,  and  paperwidth  commands  in the DESC
          file; it accepts the same arguments as  the  papersize  command.
          See groff_font (5) for details.

   -v     Print the version number.

          Set the foundry to use for selecting fonts of the same name.

   -e     Forces gropdf to embed ALL fonts (even the 14 base PDF fonts).

   -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.

          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 cmapfilename or have no CMap at all  by
          omitting the argument.


   The  input to gropdf must be in the format output by troff(1).  This is
   described in groff_out(5).

   In addition, the device and font description files for the device  used
   must  meet  certain  requirements:  The  resolution  must be an integer
   multiple of 72 times the sizescale.  The pdf device uses  a  resolution
   of 72000 and a sizescale of 1000.

   The  device  description  file  must  contain  a  valid paper size; see
   groff_font(5) for more information.  gropdf uses the same Type 1  Adobe
   postscript fonts as the grops device driver.  Although the PDF Standard
   allows the use of other font types (like TrueType) this  implementation
   only  accepts  the  Type  1  postscript  font.   Fewer Type 1 fonts are
   supported  natively  in  PDF  documents  than  the  standard  35  fonts
   supported  by  grops and all postscript printers, but all the fonts are
   available since any which aren't supported natively  are  automatically
   embedded in the PDF.

   gropdf supports the concept of foundries, that is different versions of
   basically the same font.  During install a Foundry file controls  where
   fonts  are  found and builds groff fonts from the files it discovers on
   your system.

   Each font description file must contain a command

          internalname psname

   which says that the PostScript name  of  the  font  is  psname.   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 the character
   does  not  have  a  groff  name.  Every character in the font file must
   exist in the PostScript font, and the widths given  in  the  font  file
   must match the widths used in the PostScript font.

   Note that gropdf is currently only able to display the first 256 glyphs
   in any font.  This restriction will be lifted in a later version.

   gropdf can automatically include the downloadable  fonts  necessary  to
   print the document.  Fonts may be in PFA or PFB format.

   Any  downloadable  fonts  which  should,  when required, be included by
   gropdf       must       be       listed       in        the        file
   /usr/share/groff/1.22.3/font/devpdf/download;  this  should  consist of
   lines of the form

          foundry font filename

   where foundry is the foundry name or blank  for  the  default  foundry.
   font  is  the  PostScript name of the font, and filename is the name of
   the file containing the font; lines beginning with #  and  blank  lines
   are ignored; fields must be separated by tabs (spaces are not allowed);
   filename is searched for using the same  mechanism  that  is  used  for
   groff font metric files.  The download file itself is also searched for
   using this mechanism; currently, only the first found file in the  font
   path  is  used.   Foundry names are usually a single character (such as
   'U' for the URW Foundry)  or  blank  for  the  default  foundry.   This
   default uses the same fonts as ghostscript uses when it embeds fonts in
   a PDF file.

   In the default setup there are styles called R, I, B, and BI mounted at
   font  positions  1 to 4.  The fonts are grouped into families A, BM, C,
   H, HN, N, P, and T 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

   There is also the following font which is not a member of a family:

          ZCMI   ZapfChancery-MediumItalic

   There are also some special fonts called S for the PS Symbol font.  The
   lower  case  greek  characters  are automatically slanted (to match the
   SymbolSlanted font (SS) available to  postscript).   Zapf  Dingbats  is
   available  as  ZD,  the "hand pointing left" glyph (\[lh]) is available
   since it has been defined  using  the  \X'pdf:  xrev'  extension  which
   reverses the direction of letters within words.

   The  default  color  for  \m and \M is black; for colors defined in the
   'rgb'  color  space  setrgbcolor  is  used,  for   'cmy'   and   'cmyk'
   setcmykcolor,  and  for  'gray'  setgray.   Note that setcmykcolor is a
   PostScript LanguageLevel 2 command and thus not available on some older

   gropdf  understands some of the X commands produced using the \X escape
   sequences  supported  by  grops.   Specifically,   the   following   is

   \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 gpic.

   \X'ps: exec grestore'
          Again used by gpic to restore 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'  for  using   most   of   the   PDF

   All other ps: tags are silently ignored.

   One \X special used by the DVI driver is also recognised:

          where  the  paper-size  parameter  is  the same as the papersize
          command.  See groff_font(5) for details.  This  means  that  you
          can  alter  the  page  size  at  will  within the PDF file being
          created by gropdf.  If you do want to change the paper size,  it
          must be done before you start creating the page.

   In addition, gropdf supports its own suite of pdf: tags.  The following
   tags are supported:

   \X'pdf: pdfpic file alignment width height line-length'
          Place an image of the specified width containing the PDF drawing
          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 linelength
          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.

   \X'pdf: xrev'
          This toggles a flag which reverses  the  direction  of  printing
          letter  by  letter,  i.e., each separate letter is reversed, not
          the entire word.  This is useful for reversing the direction  of
          glyphs  in  the  Dingbats  font.   To  return to normal printing
          repeat the command again.

   \X'pdf: markstart /ANN definition'
          The macros which support PDF Bookmarks use this call  internally
          to  start  the  definition  of  bookmark hotspot (user will have
          called '.pdfhref L' with the text which  will  become  the  'hot
          spot'  region).   Normally this is never used except from within
          the pdfmark macros.

   \X'pdf: markend'
          The macros which support PDF Bookmarks use this call  internally
          to  stop  the  definition  of  bookmark  hotspot (user will have
          called '.pdfhref L' with the text which  will  become  the  'hot
          spot'  region).   Normally this is never used except from within
          the pdfmark macros.

   \X'pdf: marksuspend'
   \X'pdf: markrestart'
          If you are using page traps to produce headings, footings, etc.,
          you  need  to  use  these  in  case  a 'hot spot' crosses a page
          boundary, otherwise any text output by the  heading  or  footing
          macro  will  be  marked as part of the 'hot spot'.  To stop this
          happening just place '.pdfmarksuspend' and '.pdfmarkrestart'  at
          the  start and end of the page trap macro, respectively.  (These
          are just convenience macros  which  emit  the  \X  code.   These
          macros must only be used within page traps.)

   Importing graphics
   gropdf  only  supports importing other PDF files as graphics.  But that
   PDF file may contain any of the graphic formats supported  by  the  PDF
   standard  (such  as  JPEG,  PNG,  GIF, etc.).  So any application which
   outputs PDF can be used as an embedded file in 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.  So, in inkscape(1)  or  gimp(1)
   (for example) make sure the canvas size just fits the image.

   The  PDF  parser used in gropdf has not been rigorously tested with all
   possible applications which produce PDFs.  If you find  a  single  page
   PDF  which fails to import properly, it is worth running it through the
   pdftk(1) program by issuing the command:

          pdftk oldfile.pdf output newfile.pdf

   You may find that newfile.pdf will now load successfully.

   TrueType and other font formats
   gropdf does not support any other fonts except Adobe  Type  1  (PFA  or


   This section gives a summary of the above explanations; it can serve as
   a step-by-step font installation guide for gropdf.

    *  Convert your font to something groff understands.  This is either a
       PostScript  Type  1 font in either PFA or PFB, together with an AFM

       The very first line in a PFA/PFB file contains this:


       A PFB file has this also in the  first  line,  but  the  string  is
       preceded with some binary bytes.

    *  Convert  the  AFM  file  to  a groff font description file with the
       afmtodit(1) program.  An example call is

              afmtodit Foo-Bar-Bold.afm map/textmap FBB

       which converts the metric file 'Foo-Bar-Bold.afm' to the groff font
       'FBB'.   If  you  have a font family which comes with normal, bold,
       italic, and bold italic faces, it is recommended to use the letters
       R, B, I, and BI, respectively, as postfixes in the groff font names
       to make groff's '.fam' request work.  An example is groff's  built-
       in  Times-Roman font: The font family name is T, and the groff font
       names are TR, TB, TI, and TBI.

    *  Install both the groff font description files and the  fonts  in  a
       'devpdf'  subdirectory of the font path which groff finds.  See the
       ENVIRONMENT section in the troff(1) man page which lists the actual
       value  of the font path.  Note that groff doesn't use the AFM files
       (but it is a good idea to store them anyway).

    *  Register all fonts which must be downloaded to the printer  in  the
       'devpdf/download'  file.  Only the first occurrence of this file in
       the font path is read.  This means that you should copy the default
       'download'  file  to  the first directory in your font path and add
       your fonts there.  To continue the above example we assume that the
       PS font name for Foo-Bar-Bold.pfa is 'XY-Foo-Bar-Bold' (the PS font
       name is stored in the internalname field in  the  'FBB'  file)  and
       belongs to foundry 'Fcq] thus the following line should be added to

              F XY-Foo-Bar-Bold Foo-Bar-Bold.pfa

       Use a tab character to separate the fields, and the 'foundry' field
       should be null for the default foundry.


          A  list  of  directories  in  which  to  search  for the devname
          directory  in  addition  to  the  default  ones.   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) for more details.

          A  timestamp  (expressed as seconds since the Unix epoch) to use
          as the creation timestamp in place of the current time.


          Device description file.

          Font description file for font F.

          Font description file for font F (using foundry  U  rather  than
          the default foundry).

          List of downloadable fonts.

          A Perl script used during install to locate suitable fonts.

          Encoding used for text fonts.

          Macros for use with gropdf; automatically loaded by troffrc.


   afmtodit(1), groff(1), grops(1), troff(1), grops(1), pfbtops(1),
   groff_out(5), groff_font(5), groff_char(7), groff_tmac(5)


   Copyright  2011-2014 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
   manual provided the copyright notice and this permission notice are
   preserved on all copies.

   Permission is granted to copy and distribute modified versions of this
   manual under the conditions for verbatim copying, provided that the
   entire resulting derived work is distributed under the terms of a
   permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
   manual into another language, under the above conditions for modified
   versions, except that this permission notice may be included in
   translations approved by the Free Software Foundation instead of in the
   original English.


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.