Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



GROPS(1)                                                                                            GROPS(1)



NAME
       grops - PostScript driver for groff

SYNOPSIS
       grops [ -glmv ] [ -bn ] [ -cn ] [ -Fdir ] [ -Idir ] [ -ppapersize ] [ -Pprologue ] [ -wn ]
             [ files... ]

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

DESCRIPTION
       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  stan-dard standard
       dard input.  PostScript output is written to the standard 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 concatenated output it is neces-sary necessary
       sary to deactivate DSC handling in the printing program or previewer.

OPTIONS
       -bn    Provide workarounds for older printers, broken spoolers, and previewers.  Normally grops  pro-duces produces
              duces  output  at PostScript LanguageLevel 2 that conforms to the Document Structuring Conven-tions Conventions
              tions 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 comment.

              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 %%BeginDocument and  %%EndDocument  com-ments. comments.
              ments.

              Add  8  if  the first line of the PostScript output should be %!PS-Adobe-2.0 rather than %!PS-Adobe-3.0; %!PSAdobe-3.0;
              Adobe-3.0; this is needed when using Sun's Newsprint with a printer that requires page  rever-sal. reversal.
              sal.

              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  encapsu-lated encapsulated
              lated 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.

       -Fdir  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  correct  only if the imageable area is vertically centered on the page.  This
              option allows you to generate documents that can be printed both on letter (8.5x11) paper  and
              on A4 paper without change.

       -Idir  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  abso-lute absolute
              lute path.

       -l     Print the document in landscape format.

       -m     Turn manual feed on for the document.

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

       -Pprologue-file
              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 GROPS_PROLOGUE.

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

       -v     Print the version number.

USAGE
       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, and SS, containing slanted  lower-case lowercase
       case  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 \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  Post-Script PostScript
       Script 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.

       \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 procedure 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 defi-nitions definitions
              nitions to this dictionary, you should allocate space for them using \X'ps mdef n'.  Any defi-nitions definitions
              nitions  will  persist only until the end of the page.  If you use the \Y escape sequence with
              an argument that names a macro, code can extend over multiple lines.  For example,

                     .nr x 1i
                     .de y
                     ps: exec
                     \nx u 0 rlineto
                     stroke
                     ..
                     \Yy

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

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

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

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

       \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
              integers  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 cor-ner corner
              ner of the graphic is located at the position associated with \X command.  If the height argu-ment argument
              ment is omitted it will be scaled uniformly in the x and y directions so that it has the spec-ified specified
              ified width.  Note that the contents of the \X command are not interpreted by troff; so verti-cal vertical
              cal space for the graphic is not automatically added, and the width and height  arguments  are
              not  allowed  to  have  attached scaling indicators.  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.

              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 commands 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 gxditview).

       The input to grops 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 require-ments. requirements.
       ments.  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 mul-tiple multiple
       tiple 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

              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 PostScript font, not only 256.  enc_file (or the
       default encoding 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 produces on
       the fly.

       grops can automatically include the downloadable fonts necessary to print the document.   Such  fonts
       must  be  in  PFA  format.   Use pfbtops(1) to convert a Type 1 font in PFB format.  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.

       If the file containing a downloadable font or imported document conforms to the Adobe Document Struc-turing Structuring
       turing Conventions, then grops will interpret any comments in the files sufficiently 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  depen-dencies. dependencies.
       dencies.   For  example,  suppose that you have a downloadable font called Garamond, and also a down-loadable downloadable
       loadable font called Garamond-Outline 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 pro-vided provided
       vided  that  the  downloadable font file for Garamond-Outline indicates its dependence on Garamond by
       means of the Document Structuring Conventions, for example by beginning with the following lines

              %!PS-Adobe-3.0 Resource-Font
              %%DocumentNeededResources: font Garamond
              %%EndComments
              %%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 %%DocumentSuppliedResources comment.

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

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

              groff -P-b16 foo > foo.ps
              gs -dNOPAUSE -sDEVICE=bbox -- foo.ps 2> foo.bbox
              cat foo.ps | 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 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://www.giga.or.at/pub/nih/ttftot42/ <ftp://www.giga.or.at/pub/nih/ttftot42/>.

ENVIRONMENT
       GROPS_PROLOGUE
              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 variable.

FILES
       /usr/share/groff/1.19.2/font/devps/DESC      Device description file.

       /usr/share/groff/1.19.2/font/devps/F         Font description file for font F.

       /usr/share/groff/1.19.2/font/devps/download  List of downloadable fonts.

       /usr/share/groff/1.19.2/font/devps/text.enc  Encoding used for text fonts.

       /usr/share/groff/1.19.2/tmac/ps.tmac         Macros for use with grops; automatically loaded by trof-frc troffrc
                                                    frc

       /usr/share/groff/1.19.2/tmac/pspic.tmac      Definition  of  PSPIC  macro,  automatically  loaded  by
                                                    ps.tmac.

       /usr/share/groff/1.19.2/tmac/psold.tmac      Macros to disable use of characters not present in older
                                                    PostScript printers (e.g. `eth' or `thorn').

       /tmp/gropsXXXXXX                             Temporary file.

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

       PostScript Language Document Structuring Conventions Specification <http://partners.adobe.com/public/
       developer/en/ps/5001.DSC_Spec.pdf>



Groff Version 1.19.2                           21 January 2005                                      GROPS(1)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback