man pages section 1: User Commands

Exit Print View

Updated: July 2014

grops (1)


grops - PostScript driver for groff


grops [ -glmv ] [ -bn ] [ -cn ] [ -Fdir ] [ -Idir ] [ -p-
papersize ] [ -Pprologue ] [ -wn ] [ files... ]

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


User Commands                                            GROPS(1)

     grops - PostScript driver for groff

     grops [ -glmv ] [ -bn ] [ -cn ] [ -Fdir ] [ -Idir ] [ -p-
           papersize ] [ -Pprologue ] [ -wn ] [ files... ]

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

     grops  translates  the  output  of  GNU troff to PostScript.
     Normally grops should be invoked by using the groff  command
     with  a  -Tps  option.   (Actually,  this is the default for
     groff.)  If no files are given, grops will read the standard
     input.   A  filename  of - will also cause grops to read the
     standard input.  PostScript output is written to  the  stan-
     dard  output.   When  grops  is  run by groff options can be
     passed to grops using the groff -P option.

     Note that grops doesn't produce a valid  document  structure
     (conforming  to  the  Document  Structuring  Convention)  if
     called with multiple file arguments.  To print such concate-
     nated  output  it is necessary to deactivate DSC handling in
     the printing program or previewer.

     -bn  Provide workarounds for older printers,  broken  spool-
          ers, and previewers.  Normally grops produces output at
          PostScript LanguageLevel 2 that conforms to  the  Docu-
          ment  Structuring  Conventions version 3.0.  Some older
          printers, spoolers, and previewers  can't  handle  such
          output.   The  value  of  n controls what grops does to
          make its output acceptable to such programs.   A  value
          of 0 will cause grops not to employ any workarounds.

          Add 1 if no %%BeginDocumentSetup and %%EndDocumentSetup
          comments should be generated; this is needed for  early
          versions  of  TranScript  that get confused by anything
          between the %%EndProlog comment and  the  first  %%Page

          Add  2  if  lines  in  included files beginning with %!
          should be  stripped  out;  this  is  needed  for  Sun's
          pageview previewer.

          Add  4  if  %%Page,  %%Trailer and %%EndProlog comments
          should be stripped  out  of  included  files;  this  is
          needed  for spoolers that don't understand the %%Begin-
          Document and %%EndDocument comments.

          Add 8 if the first line of the PostScript output should

Groff Version 1.19.Last change: 21 January 2005                 1

User Commands                                            GROPS(1)

          be  %!PS-Adobe-2.0  rather than %!PS-Adobe-3.0; this is
          needed when using Sun's Newsprint with a  printer  that
          requires page reversal.

          Add  16 if no media size information should be included
          in the document (this is, neither  use  %%DocumentMedia
          nor  the  setpagedevice  PostScript command).  This was
          the behaviour of groff version 1.18.1 and  earlier;  it
          is  needed  for  older  printers which don't understand
          PostScript LanguageLevel 2.  It is  also  necessary  if
          the  output is further processed to get an encapsulated
          PS (EPS) file -- see below.

          The default value can be specified by a

               broken n

          command in the DESC file.  Otherwise the default  value
          is 0.

     -cn  Print n copies of each page.

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

     -g   Guess  the page length.  This generates PostScript code
          that guesses the page length.  The guess will  be  cor-
          rect  only if the imageable area is vertically centered
          on the page.  This option allows you to generate  docu-
          ments that can be printed both on letter (8.5x11) paper
          and on A4 paper without change.

          This option may be  used  to  specify  a  directory  to
          search for files on the command line and files named in
          \X'ps: import' and \X'ps: file' escapes.   The  current
          directory is always searched first.  This option may be
          specified more  than  once;  the  directories  will  be
          searched  in  the order specified.  No directory search
          is performed for  files  specified  using  an  absolute

     -l   Print the document in landscape format.

     -m   Turn manual feed on for the document.

          Set  physical  dimension  of output medium.  This over-
          rides the papersize, paperlength, and  paperwidth  com-
          mands  in  the DESC file; it accepts the same arguments

Groff Version 1.19.Last change: 21 January 2005                 2

User Commands                                            GROPS(1)

          as the  papersize  command.   See  groff_font  (5)  for

          Use  the  file  prologue-file (in the font path) as the
          prologue instead of the default prologue file prologue.
          This   option   overrides   the   environment  variable

     -wn  Lines should be drawn using  a  thickness  of  n  thou-
          sandths  of  an  em.   If this option is not given, the
          line thickness defaults to 0.04 em.

     -v   Print the version number.

     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

          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

Groff Version 1.19.Last change: 21 January 2005                 3

User Commands                                            GROPS(1)

          TBI  Times-BoldItalic

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

          ZCMI ZapfChancery-MediumItalic

     There are also some special fonts called S for the PS Symbol
     font,  and  SS,  containing  slanted lowercase Greek letters
     taken from PS Symbol.  Zapf Dingbats is available as ZD  and
     a reversed version of ZapfDingbats (with symbols pointing in
     the opposite direction) is available as ZDR; most characters
     in these fonts are unnamed and must be accessed using [rs]N.

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

     grops understands various X commands produced using  the  \X
     escape  sequence;  grops  will  only interpret commands that
     begin with a ps: tag.

     [rs]X'ps: exec code'
          This executes  the  arbitrary  PostScript  commands  in
          code.   The  PostScript currentpoint will be set to the
          position of the \X command before executing code.   The
          origin  will be at the top left corner of the page, and
          y coordinates will increase down the  page.   A  proce-
          dure u will be defined that converts groff units to the
          coordinate system in effect.  For example,

               .nr x 1i
               \X'ps: exec \nx u 0 rlineto stroke'

          will draw a horizontal line one inch  long.   code  may
          make  changes  to  the  graphics state, but any changes
          will persist only to the end of the page.  A dictionary
          containing  the  definitions  specified  by the def and
          mdef will be on top of the dictionary stack.   If  your
          code  adds  definitions  to this dictionary, you should
          allocate space for them  using  [rs]X'ps mdef n'.   Any
          definitions  will  persist  only  until  the end of the
          page.  If you use the \Y escape sequence with an  argu-
          ment  that names a macro, code can extend over multiple
          lines.  For example,

               .nr x 1i
               .de y
               ps: exec

Groff Version 1.19.Last change: 21 January 2005                 4

User Commands                                            GROPS(1)

               \nx u 0 rlineto

          is another way to draw a horizontal line one inch long.

     [rs]X'ps: file name'
          This  is  the  same as the exec command except that the
          PostScript code is read from file name.

     [rs]X'ps: def code'
          Place a PostScript definition contained in code in  the
          prologue.   There  should be at most one definition per
          \X command.  Long definitions can be split over several
          \X  commands;  all the code arguments are simply joined
          together separated by newlines.   The  definitions  are
          placed in a dictionary which is automatically pushed on
          the dictionary stack when an exec command is  executed.
          If you use the \Y escape sequence with an argument that
          names a macro, code can extend over multiple lines.

     [rs]X'ps: mdef n code'
          Like def, except that code may contain up to n  defini-
          tions.   grops  needs to know how many definitions code
          contains so that it can create an  appropriately  sized
          PostScript dictionary to contain them.

     [rs]X'ps: import file llx lly urx ury width [ height ]'
          Import  a  PostScript graphic from file.  The arguments
          llx, lly, urx, and ury give the  bounding  box  of  the
          graphic  in  the  default PostScript coordinate system;
          they should all be integers; llx and lly are the x  and
          y  coordinates of the lower left corner of the graphic;
          urx and ury are the x and y coordinates  of  the  upper
          right corner of the graphic; width and height are inte-
          gers that give the desired width and  height  in  groff
          units  of  the  graphic.  The graphic will be scaled so
          that it has this width and  height  and  translated  so
          that the lower left corner of the graphic is located at
          the position associated with \X command.  If the height
          argument  is omitted it will be scaled uniformly in the
          x and y directions so that it has the specified  width.
          Note that the contents of the \X command are not inter-
          preted by troff; so vertical space for the  graphic  is
          not automatically added, and the width and height argu-
          ments are not allowed to have attached scaling  indica-
          tors.   If  the PostScript file complies with the Adobe
          Document  Structuring  Conventions   and   contains   a
          %%BoundingBox  comment,  then  the  bounding box can be
          automatically extracted from within groff by using  the
          psbb request.

Groff Version 1.19.Last change: 21 January 2005                 5

User Commands                                            GROPS(1)

          See  groff_tmac(5) for a description of the PSPIC macro
          which provides a convenient  high-level  interface  for
          inclusion of PostScript graphics.

     \X'ps: invis'
     \X'ps: endinvis'
          No  output  will be generated for text and drawing com-
          mands that are bracketed with these \X commands.  These
          commands  are  intended  for use when output from troff
          will be previewed before being processed with grops; if
          the  previewer  is unable to display certain characters
          or other constructs, then other  substitute  characters
          or  constructs can be used for previewing by bracketing
          them with these \X commands.

          For example, gxditview is not able to display a  proper
          \(em  character  because  the standard X11 fonts do not
          provide it; this problem can be overcome  by  executing
          the following request

               .char \(em \X'ps: invis'\
               \Z'\v'-.25m'\h'.05m'\D'l .9m 0'\h'.05m''\
               \X'ps: endinvis'\(em

          In  this  case, gxditview will be unable to display the
          \(em character and will draw the  line,  whereas  grops
          will print the \(em character and ignore the line (this
          code is already in file Xps.tmac which will  be  loaded
          if  a  document  intended  for  grops is previewed with

     The  input  to  grops  must  be  in  the  format  output  by
     gtroff(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 device  and
     font description files supplied for ps device meet all these
     requirements.  afmtodit(1) can be used to create font  files
     from  AFM files.  The resolution must be an integer multiple
     of 72 times the sizescale.  The ps 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.

     Each font description file must contain a command

          internalname psname

     which says that the PostScript name of the font  is  psname.
     It may also contain a command

Groff Version 1.19.Last change: 21 January 2005                 6

User Commands                                            GROPS(1)

          encoding enc_file

     which  says  that  the  PostScript  font should be reencoded
     using the encoding described in enc_file; this  file  should
     consist of a sequence of lines of the form:

          pschar code

     where  pschar  is  the PostScript name of the character, and
     code is its position in the encoding expressed as a  decimal
     integer;  valid  values  are  in  the range 0 to 255.  Lines
     starting with # and blank lines are ignored.  The  code  for
     each character given in the font file must correspond to the
     code for the character in encoding file, or to the  code  in
     the  default encoding for the font if the PostScript font is
     not to be reencoded.  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.   grops  will assume that a character
     with a groff name of space is blank (makes no marks  on  the
     page);  it can make use of such a character to generate more
     efficient and compact PostScript output.

     Note that grops is able to display all  glyphs  in  a  Post-
     Script  font, not only 256.  enc_file (or the default encod-
     ing if no encoding file specified) just defines the order of
     glyphs  for  the  first 256 characters; all other glyphs are
     accessed with additional encoding vectors which  grops  pro-
     duces on the fly.

     grops  can automatically include the downloadable fonts nec-
     essary to print the document.  Such fonts  must  be  in  PFA
     format.  Use pfbtops(1) to convert a Type 1 font in PFB for-
     mat.  Any downloadable fonts which should, when required, be
     included   by   grops   must   be   listed   in   the   file
     /usr/share/groff/1.19.2/font/devps/download;   this   should
     consist of lines of the form

          font filename

     where  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 may be separated
     by tabs or spaces; filename will be searched for  using  the
     same  mechanism  that  is  used for groff font metric files.
     The download file itself will also  be  searched  for  using
     this  mechanism; currently, only the first found file in the
     font path is used.

Groff Version 1.19.Last change: 21 January 2005                 7

User Commands                                            GROPS(1)

     If the file containing a downloadable font or imported docu-
     ment conforms to the Adobe Document Structuring Conventions,
     then grops will interpret any comments in the  files  suffi-
     ciently  to  ensure  that  its own output is conforming.  It
     will also supply any needed font resources that  are  listed
     in  the  download file as well as any needed file resources.
     It is also able to handle inter-resource dependencies.   For
     example,  suppose  that  you have a downloadable font called
     Garamond, and also a downloadable font called  Garamond-Out-
     line  which  depends  on  Garamond  (typically  it  would be
     defined to copy Garamond's font dictionary, and  change  the
     PaintType),  then  it  is  necessary  for Garamond to appear
     before Garamond-Outline in the PostScript  document.   grops
     will  handle  this automatically provided that the download-
     able font file for Garamond-Outline indicates its dependence
     on  Garamond  by  means  of the Document Structuring Conven-
     tions, for example by beginning with the following lines

          %!PS-Adobe-3.0 Resource-Font
          %%DocumentNeededResources: font Garamond
          %%IncludeResource: font Garamond

     In this case both Garamond and Garamond-Outline  would  need
     to  be  listed  in  the  download file.  A downloadable font
     should not include its own  name  in  a  %%DocumentSupplied-
     Resources comment.

     grops  will  not  interpret  %%DocumentFonts  comments.  The
     %%DocumentNeededResources,      %%DocumentSuppliedResources,
     %%IncludeResource,  %%BeginResource,  and %%EndResource com-
     ments   (or   possibly   the   old    %%DocumentNeededFonts,
     %%DocumentSuppliedFonts,   %%IncludeFont,  %%BeginFont,  and
     %%EndFont comments) should be used.

  Encapsulated PostScript
     grops itself doesn't emit bounding  box  information.   With
     the  help of GhostScript the following commands will produce
     an encapsulated PS file foo.eps from input file foo:

          groff -P-b16 foo >
          gs -dNOPAUSE -sDEVICE=bbox -- 2> foo.bbox
          cat | sed -e '/%%Orientation/rfoo.bbx' > foo.eps
          rm foo.bbx

  TrueType fonts
     TrueType  fonts can be used with grops if converted first to
     Type 42 format, an especial PostScript wrapper equivalent to
     the  PFA  format mentioned in pfbtops(1).  There are several
     different methods to generate a type42 wrapper and  most  of
     them  involve  the  use  of a PostScript interpreter such as
     Ghostscript -- see gs(1).  Yet, the easiest method  involves

Groff Version 1.19.Last change: 21 January 2005                 8

User Commands                                            GROPS(1)

     the  use  of  the  application  ttftot42.  This program uses
     freetype(3) (version 1.3.1) to generate type42 font wrappers
     and well-formed AFM files that can be fed to the afmtodit(1)
     script to create appropriate metric  files.   The  resulting
     font   wrappers  should  be  added  to  the  download  file.
     ttftot42 source code can be downloaded from ftp:// <

          If this is set to foo, then grops will use the file foo
          (in the font path) instead of the default prologue file
          prologue.  The option  -P  overrides  this  environment

          Device description file.

          Font description file for font F.

          List of downloadable fonts.

          Encoding used for text fonts.

          Macros  for  use  with  grops;  automatically loaded by

          Definition of  PSPIC  macro,  automatically  loaded  by

          Macros  to  disable  use  of  characters not present in
          older PostScript printers (e.g. `eth' or `thorn').

          Temporary file.

     See  attributes(5)  for  descriptions   of   the   following

Groff Version 1.19.Last change: 21 January 2005                 9

User Commands                                            GROPS(1)

     |Availability   | text/groff/groff-core |
     |Stability      | Uncommitted           |
     afmtodit(1),  groff(1), gtroff(1), pfbtops(1), groff_out(5),
     groff_font(5), groff_char(7), groff_tmac(5)

     PostScript Language Document Structuring Conventions Speci-
     fication <

     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open source community  website  at

Groff Version 1.19.Last change: 21 January 2005                10