1GROPS(1)                    General Commands Manual                   GROPS(1)
2
3
4

NAME

6       grops - PostScript driver for groff
7

SYNOPSIS

9       grops [-glmv] [-b n] [-c n] [-F dir] [-I dir] [-p papersize]
10             [-P prologue] [-w n] [files ...]
11
12       It is possible to have whitespace between a command line option and its
13       parameter.
14

DESCRIPTION

16       grops translates the output of GNU troff to PostScript.  Normally grops
17       should be invoked by using  the  groff  command  with  a  -Tps  option.
18       (Actually,  this  is  the  default  for groff.)  If no files are given,
19       grops reads the standard input.  A filename of - also causes  grops  to
20       read  the standard input.  PostScript output is written to the standard
21       output.  When grops is run by groff options  can  be  passed  to  grops
22       using groff's -P option.
23
24       Note  that grops doesn't produce a valid document structure (conforming
25       to the Document Structuring Convention) if called  with  multiple  file
26       arguments.   To print such concatenated output it is necessary to deac‐
27       tivate DSC handling in the printing program or previewer.  See  section
28       FONT INSTALLATION below for a guide how to install fonts for grops.
29

OPTIONS

31       -bn    Provide  workarounds  for  older  printers, broken spoolers, and
32              previewers.  Normally grops produces output at  PostScript  Lan‐
33              guageLevel  2  that conforms to the Document Structuring Conven‐
34              tions version 3.0.  Some older printers, spoolers, and  preview‐
35              ers  can't  handle  such  output.   The value of n controls what
36              grops does to make its output acceptable to  such  programs.   A
37              value of 0 causes grops not to employ any workarounds.
38
39              Add 1 if no %%BeginDocumentSetup and %%EndDocumentSetup comments
40              should be generated; this is needed for early versions of  Tran‐
41              Script  that  get  confused  by anything between the %%EndProlog
42              comment and the first %%Page comment.
43
44              Add 2 if lines in included files beginning  with  %!  should  be
45              stripped out; this is needed for Sun's pageview previewer.
46
47              Add  4  if  %%Page, %%Trailer and %%EndProlog comments should be
48              stripped out of included files; this is needed for spoolers that
49              don't understand the %%BeginDocument and %%EndDocument comments.
50
51              Add 8 if the first line of the PostScript output should be %!PS-
52              Adobe-2.0 rather than %!PS-Adobe-3.0; this is needed when  using
53              Sun's Newsprint with a printer that requires page reversal.
54
55              Add  16  if  no media size information should be included in the
56              document (this is, neither  use  %%DocumentMedia  nor  the  set‐
57              pagedevice PostScript command).  This was the behaviour of groff
58              version 1.18.1 and earlier; it  is  needed  for  older  printers
59              which  don't  understand PostScript LanguageLevel 2.  It is also
60              necessary if the output is further processed to get an  encapsu‐
61              lated PS (EPS) file – see below.
62
63              The default value can be specified by a
64
65                     broken n
66
67              command in the DESC file.  Otherwise the default value is 0.
68
69       -cn    Print n copies of each page.
70
71       -Fdir  Prepend  directory  dir/devname to the search path for prologue,
72              font, and device description files; name  is  the  name  of  the
73              device, usually ps.
74
75       -g     Guess  the  page  length.   This  generates PostScript code that
76              guesses the page length.  The  guess  is  correct  only  if  the
77              imageable  area is vertically centered on the page.  This option
78              allows you to generate documents that can  be  printed  both  on
79              letter (8.5×11) paper and on A4 paper without change.
80
81       -Idir  This  option  may  be used to add a directory to the search path
82              for files on the command line and files named in \X'ps:  import'
83              and  \X'ps:  file' escapes.  The search path is initialized with
84              the current directory.  This option may be specified  more  than
85              once;  the  directories are then searched in the order specified
86              (but before the current directory).  If you  want  to  make  the
87              current  directory  be read before other directories, add -I. at
88              the appropriate place.
89
90              No directory search is performed for files with an absolute file
91              name.
92
93       -l     Print the document in landscape format.
94
95       -m     Turn manual feed on for the document.
96
97       -ppaper-size
98              Set  physical  dimension  of  output medium.  This overrides the
99              papersize, paperlength, and  paperwidth  commands  in  the  DESC
100              file;  it  accepts  the same arguments as the papersize command.
101              See groff_font (5) for details.
102
103       -Pprologue-file
104              Use the file prologue-file (in the font path)  as  the  prologue
105              instead  of  the  default  prologue  file prologue.  This option
106              overrides the environment variable GROPS_PROLOGUE.
107
108       -wn    Lines should be drawn using a thickness of n thousandths  of  an
109              em.  If this option is not given, the line thickness defaults to
110              0.04 em.
111
112       -v     Print the version number.
113

USAGE

115       The input to grops must be in the format output by troff(1).   This  is
116       described in groff_out(5).
117
118       In  addition, the device and font description files for the device used
119       must meet certain requirements: The resolution must be an integer  mul‐
120       tiple  of  72  times the sizescale.  The ps device uses a resolution of
121       72000 and a sizescale of 1000.
122
123       The device description file  must  contain  a  valid  paper  size;  see
124       groff_font(5) for more information.
125
126       Each font description file must contain a command
127
128              internalname psname
129
130       which says that the PostScript name of the font is psname.  It may also
131       contain a command
132
133              encoding enc_file
134
135       which says that the PostScript  font  should  be  reencoded  using  the
136       encoding  described in enc_file; this file should consist of a sequence
137       of lines of the form:
138
139              pschar code
140
141       where pschar is the PostScript name of the character, and code  is  its
142       position  in  the encoding expressed as a decimal integer; valid values
143       are in the range 0 to 255.  Lines starting with # and blank  lines  are
144       ignored.   The code for each character given in the font file must cor‐
145       respond to the code for the character in encoding file, or to the  code
146       in  the  default encoding for the font if the PostScript font is not to
147       be reencoded.  This code can be used with the  \N  escape  sequence  in
148       troff  to  select  the character, even if the character does not have a
149       groff name.  Every character in the font file must exist in  the  Post‐
150       Script  font,  and  the  widths  given  in the font file must match the
151       widths used in the PostScript font.  grops  assumes  that  a  character
152       with  a  groff  name of space is blank (makes no marks on the page); it
153       can make use of such a character to generate more efficient and compact
154       PostScript output.
155
156       Note that grops is able to display all glyphs in a PostScript font, not
157       only 256.  enc_file (or the default encoding if no encoding file speci‐
158       fied)  just  defines  the order of glyphs for the first 256 characters;
159       all other glyphs are accessed with additional  encoding  vectors  which
160       grops produces on the fly.
161
162       grops  can  automatically  include  the downloadable fonts necessary to
163       print the document.  Such fonts must be in PFA format.  Use  pfbtops(1)
164       to  convert  a Type 1 font in PFB format.  Any downloadable fonts which
165       should, when required, be included by grops must be listed in the  file
166       /usr/share/groff/1.20.1/font/devps/download;  this  should  consist  of
167       lines of the form
168
169              font filename
170
171       where font is the PostScript name of the font, and filename is the name
172       of the file containing the font; lines beginning with # and blank lines
173       are ignored; fields may be separated by tabs  or  spaces;  filename  is
174       searched  for using the same mechanism that is used for groff font met‐
175       ric files.  The download file itself is also searched  for  using  this
176       mechanism;  currently,  only  the  first found file in the font path is
177       used.
178
179       If the file containing a downloadable font or  imported  document  con‐
180       forms  to the Adobe Document Structuring Conventions, then grops inter‐
181       prets any comments in the files sufficiently to  ensure  that  its  own
182       output  is conforming.  It also supplies any needed font resources that
183       are listed in the download file as well as any needed  file  resources.
184       It  is  also  able to handle inter-resource dependencies.  For example,
185       suppose that you have a downloadable font called Garamond, and  also  a
186       downloadable  font  called  Garamond-Outline  which depends on Garamond
187       (typically it would be defined to copy Garamond's font dictionary,  and
188       change  the  PaintType),  then  it  is necessary for Garamond to appear
189       before Garamond-Outline in the PostScript document.  grops handles this
190       automatically  provided  that  the downloadable font file for Garamond-
191       Outline indicates its dependence on Garamond by means of  the  Document
192       Structuring  Conventions,  for  example by beginning with the following
193       lines
194
195              %!PS-Adobe-3.0 Resource-Font
196              %%DocumentNeededResources: font Garamond
197              %%EndComments
198              %%IncludeResource: font Garamond
199
200       In this case both Garamond and Garamond-Outline would need to be listed
201       in  the  download file.  A downloadable font should not include its own
202       name in a %%DocumentSuppliedResources comment.
203
204       grops does not interpret  %%DocumentFonts  comments.   The  %%Document‐
205       NeededResources,     %%DocumentSuppliedResources,    %%IncludeResource,
206       %%BeginResource,  and  %%EndResource  comments  (or  possibly  the  old
207       %%DocumentNeededFonts, %%DocumentSuppliedFonts, %%IncludeFont, %%Begin‐
208       Font, and %%EndFont comments) should be used.
209
210       In the default setup there are styles called R, I, B, and BI mounted at
211       font  positions  1 to 4.  The fonts are grouped into families A, BM, C,
212       H, HN, N, P, and T having members in each of these styles:
213
214              AR     AvantGarde-Book
215              AI     AvantGarde-BookOblique
216              AB     AvantGarde-Demi
217              ABI    AvantGarde-DemiOblique
218              BMR    Bookman-Light
219              BMI    Bookman-LightItalic
220              BMB    Bookman-Demi
221              BMBI   Bookman-DemiItalic
222              CR     Courier
223              CI     Courier-Oblique
224              CB     Courier-Bold
225              CBI    Courier-BoldOblique
226              HR     Helvetica
227              HI     Helvetica-Oblique
228              HB     Helvetica-Bold
229              HBI    Helvetica-BoldOblique
230              HNR    Helvetica-Narrow
231              HNI    Helvetica-Narrow-Oblique
232              HNB    Helvetica-Narrow-Bold
233              HNBI   Helvetica-Narrow-BoldOblique
234              NR     NewCenturySchlbk-Roman
235              NI     NewCenturySchlbk-Italic
236              NB     NewCenturySchlbk-Bold
237              NBI    NewCenturySchlbk-BoldItalic
238              PR     Palatino-Roman
239              PI     Palatino-Italic
240              PB     Palatino-Bold
241              PBI    Palatino-BoldItalic
242              TR     Times-Roman
243              TI     Times-Italic
244              TB     Times-Bold
245              TBI    Times-BoldItalic
246
247       There is also the following font which is not a member of a family:
248
249              ZCMI   ZapfChancery-MediumItalic
250
251       There are also some special fonts called S for the PS Symbol font,  and
252       SS,  containing  slanted  lowercase Greek letters taken from PS Symbol.
253       Zapf Dingbats is available as ZD, and a reversed version  of  ZapfDing‐
254       bats  (with symbols pointing in the opposite direction) is available as
255       ZDR; most characters in these fonts are unnamed and  must  be  accessed
256       using \N.
257
258       The  default  color  for  \m and \M is black; for colors defined in the
259       `rgb' color space setrgbcolor is used, for `cmy'  and  `cmyk'  setcmyk‐
260       color,  and for `gray' setgray.  Note that setcmykcolor is a PostScript
261       LanguageLevel 2 command and thus not available on some older printers.
262
263       grops understands various X  commands  produced  using  the  \X  escape
264       sequence; grops only interprets commands that begin with a ps: tag.
265
266       \X'ps: exec code'
267              This  executes  the  arbitrary PostScript commands in code.  The
268              PostScript currentpoint is set to the position of the \X command
269              before  executing code.  The origin is at the top left corner of
270              the page, and y coordinates increase down the  page.   A  proce‐
271              dure  u  is  defined that converts groff units to the coordinate
272              system in effect (provided the user doesn't change  the  scale).
273              For example,
274
275                     .nr x 1i
276                     \X'ps: exec \nx u 0 rlineto stroke'
277
278              draws a horizontal line one inch long.  code may make changes to
279              the graphics state, but any changes persist only to the  end  of
280              the  page.  A dictionary containing the definitions specified by
281              the def and mdef is on top of the  dictionary  stack.   If  your
282              code  adds  definitions  to this dictionary, you should allocate
283              space for them using  \X'ps mdef n'.   Any  definitions  persist
284              only  until  the  end  of  the  page.   If you use the \Y escape
285              sequence with an argument that names a macro,  code  can  extend
286              over multiple lines.  For example,
287
288                     .nr x 1i
289                     .de y
290                     ps: exec
291                     \nx u 0 rlineto
292                     stroke
293                     ..
294                     \Yy
295
296              is  another  way  to draw a horizontal line one inch long.  Note
297              the single backslash before `nx' – the only reason to use a num‐
298              ber  register while defining the macro `y' is to convert a user-
299              specified dimension `1i' to internal groff units  which  are  in
300              turn converted to PS units with the u procedure.
301
302              grops  wraps  user-specified  PostScript code into a dictionary,
303              nothing more.  In particular,  it  doesn't  start  and  end  the
304              inserted code with save and restore, respectively.  This must be
305              supplied by the user, if necessary.
306
307       \X'ps: file name'
308              This is the same as the exec command except that the  PostScript
309              code is read from file name.
310
311       \X'ps: def code'
312              Place a PostScript definition contained in code in the prologue.
313              There should be at most one definition  per  \X  command.   Long
314              definitions  can be split over several \X commands; all the code
315              arguments are simply joined together separated by newlines.  The
316              definitions  are  placed  in a dictionary which is automatically
317              pushed on the dictionary stack when an exec command is executed.
318              If  you use the \Y escape sequence with an argument that names a
319              macro, code can extend over multiple lines.
320
321       \X'ps: mdef n code'
322              Like def, except that code may  contain  up  to  n  definitions.
323              grops  needs  to know how many definitions code contains so that
324              it can create an appropriately sized  PostScript  dictionary  to
325              contain them.
326
327       \X'ps: import file llx lly urx ury width [ height ]'
328              Import  a PostScript graphic from file.  The arguments llx, lly,
329              urx, and ury give the bounding box of the graphic in the default
330              PostScript  coordinate  system; they should all be integers; llx
331              and lly are the x and y coordinates of the lower left corner  of
332              the  graphic;  urx  and  ury  are the x and y coordinates of the
333              upper right corner of the graphic; width and height are integers
334              that  give  the  desired  width and height in groff units of the
335              graphic.
336
337              The graphic is scaled so that it has this width and  height  and
338              translated  so  that  the  lower  left  corner of the graphic is
339              located at the position associated  with  \X  command.   If  the
340              height  argument  is omitted it is scaled uniformly in the x and
341              y directions so that it has the specified width.
342
343              Note that the contents of the \X command are not interpreted  by
344              troff;  so  vertical  space for the graphic is not automatically
345              added, and the width and height arguments  are  not  allowed  to
346              have attached scaling indicators.
347
348              If  the  PostScript file complies with the Adobe Document Struc‐
349              turing Conventions and contains a  %%BoundingBox  comment,  then
350              the  bounding  box  can  be  automatically extracted from within
351              groff by using the psbb request.
352
353              See groff_tmac(5) for a description of  the  PSPIC  macro  which
354              provides  a  convenient  high-level  interface  for inclusion of
355              PostScript graphics.
356
357       \X'ps: invis'
358       \X'ps: endinvis'
359              No output is generated for text and drawing  commands  that  are
360              bracketed  with  these \X commands.  These commands are intended
361              for use when output from troff is previewed  before  being  pro‐
362              cessed with grops; if the previewer is unable to display certain
363              characters or other constructs, then other substitute characters
364              or constructs can be used for previewing by bracketing them with
365              these \X commands.
366
367              For example, gxditview is not able  to  display  a  proper  \(em
368              character because the standard X11 fonts do not provide it; this
369              problem can be overcome by executing the following request
370
371                     .char \(em \X'ps: invis'\
372                     \Z'\v'-.25m'\h'.05m'\D'l .9m 0'\h'.05m''\
373                     \X'ps: endinvis'\(em
374
375              In this case, gxditview is unable to display the \(em  character
376              and  draws the line, whereas grops prints the \(em character and
377              ignores the line (this code is already in file Xps.tmac which is
378              loaded  if  a  document  intended  for  grops  is previewed with
379              gxditview).
380
381       If a PostScript procedure BPhook has been defined via  a  `ps: def'  or
382       `ps: mdef'  device  command,  it  is executed at the beginning of every
383       page (before anything is drawn or written by groff).  For  example,  to
384       underlay  the  page  contents  with the word `DRAFT' in light gray, you
385       might use
386
387              .de XX
388              ps: def
389              /BPhook
390              { gsave .9 setgray clippath pathbbox exch 2 copy
391                .5 mul exch .5 mul translate atan rotate pop pop
392                /NewCenturySchlbk-Roman findfont 200 scalefont setfont
393                (DRAFT) dup stringwidth pop -.5 mul -70 moveto show
394                grestore }
395              def
396              ..
397              .devicem XX
398
399       Or, to cause lines and polygons to be drawn with  square  linecaps  and
400       mitered  linejoins instead of the round linecaps and linejoins normally
401       used by grops, use
402
403              .de XX
404              ps: def
405              /BPhook { 2 setlinecap 0 setlinejoin } def
406              ..
407              .devicem XX
408
409       (square linecaps, as opposed to butt linecaps (0 setlinecap), give true
410       corners in boxed tables even though the lines are drawn unconnected).
411
412   Encapsulated PostScript
413       grops  itself  doesn't emit bounding box information.  With the help of
414       Ghostscript the following simple script, groff2eps, produces an  encap‐
415       sulated PS file.
416
417              #! /bin/sh
418              groff -P-b16 $1 >$1.ps
419              gs -dNOPAUSE -sDEVICE=bbox -- $1.ps 2>$1.bbox
420              cat $1.ps \
421              | sed -e "/^%%Orientation/r$1.bbox" \
422                    -e "/^%!PS-Adobe-3.0/s/$/ EPSF-3.0/" >$1.eps
423              rm $1.ps $1.bbox
424
425       Just say
426
427              groff2eps foo
428
429       to convert file foo to foo.eps.
430
431   TrueType and other font formats
432       TrueType  fonts  can  be  used with grops if converted first to Type 42
433       format, a special PostScript wrapper equivalent to the PFA format  men‐
434       tioned  in pfbtops(1).  There are several different methods to generate
435       a type42 wrapper and most of them  involve  the  use  of  a  PostScript
436       interpreter such as Ghostscript – see gs(1).
437
438       Yet,   the   easiest   method  involves  the  use  of  the  application
439       ttftot42(1).  This program uses freetype(3) (version 1.3.1) to generate
440       type42  font  wrappers and well-formed AFM files that can be fed to the
441       afmtodit(1) script to create appropriate metric files.   The  resulting
442       font  wrappers  should  be added to the download file.  ttftot42 source
443       code  can  be  downloaded  from  ftp://www.giga.or.at/pub/nih/ttftot42/
444       ⟨ftp://www.giga.or.at/pub/nih/ttftot42/⟩.
445
446       Another  solution  for  creating  type42  wrappers is to use FontForge,
447       available from http://fontforge.sf.nethttp://fontforge.sf.net⟩.  This
448       font editor can convert most outline font formats.
449

FONT INSTALLATION

451       This section gives a summary of the above explanations; it can serve as
452       a step-by-step font installation guide for grops.
453
454        ·  Convert your font to something groff understands.  This is either a
455           PostScript  Type 1 font in PFA format or a PostScript Type 42 font,
456           together with an AFM file.
457
458           The very first characters in a PFA file look like this:
459
460                  %!PS-AdobeFont-1.0:
461
462           A PFB file has this also in the first line, but the string is  pre‐
463           ceded with some binary bytes.
464
465           The very first characters in a Type 42 font file look like this:
466
467                  %!PS-TrueTypeFont
468
469           This is a wrapper format for TrueType fonts.  Old PS printers might
470           not support it (this is, they don't have a built-in  TrueType  font
471           interpreter).
472
473           If  your  font is in PFB format (such fonts normally have `.pfb' as
474           the file extension), you might use groff's  pfbtops(1)  program  to
475           convert  it to PFA.  For TrueType fonts, try ttftot42 or fontforge.
476           For all other font formats use fontforge  which  can  convert  most
477           outline font formats.
478
479        ·  Convert  the  AFM  file  to  a groff font description file with the
480           afmtodit(1) program.  An example call is
481
482                  afmtodit Foo-Bar-Bold.afm textmap FBB
483
484           which converts the metric file `Foo-Bar-Bold.afm' to the groff font
485           `FBB'.   If  you  have a font family which comes with normal, bold,
486           italic, and bold italic faces, it is recommended to use the letters
487           R, B, I, and BI, respectively, as postfixes in the groff font names
488           to make groff's `.fam' request work.  An example is groff's  built-
489           in  Times-Roman font: The font family name is T, and the groff font
490           names are TR, TB, TI, and TBI.
491
492        ·  Install both the groff font description files and the  fonts  in  a
493           `devps'  subdirectory  of the font path which groff finds.  See the
494           ENVIRONMENT section in the troff(1) man page which lists the actual
495           value  of the font path.  Note that groff doesn't use the AFM files
496           (but it is a good idea to store them anyway).
497
498        ·  Register all fonts which must be downloaded to the printer  in  the
499           `devps/download'  file.   Only the first occurrence of this file in
500           the font path is read.  This means that you should copy the default
501           `download'  file  to  the first directory in your font path and add
502           your fonts there.  To continue the above example we assume that the
503           PS font name for Foo-Bar-Bold.pfa is `XY-Foo-Bar-Bold' (the PS font
504           name is stored in the internalname field in the `FBB'  file),  thus
505           the following line should be added to `download'.
506
507                  XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
508

OLD FONTS

510       groff  versions  1.19.2 and earlier contain a slightly different set of
511       the 35 Adobe core fonts; the difference  is  mainly  the  lack  of  the
512       `Euro' glyph and a reduced set of kerning pairs.  For backwards compat‐
513       ibility, these old fonts are installed also in the
514
515              /usr/share/groff/1.20.1/oldfont/devps
516
517       directory.
518
519       To use them, make sure that grops finds the fonts  before  the  default
520       system  fonts  (with the same names): Either add command line option -F
521       to grops
522
523              groff -Tps -P-F -P/usr/share/groff/1.20.1/oldfont ...
524
525       or add the directory to groff's font path environment variable
526
527              GROFF_FONT_PATH=/usr/share/groff/1.20.1/oldfont
528

ENVIRONMENT

530       GROPS_PROLOGUE
531              If this is set to foo, then grops uses the file foo (in the font
532              path) instead of the default prologue file prologue.  The option
533              -P overrides this environment variable.
534
535       GROFF_FONT_PATH
536              A list of directories in which to search for the devname  direc‐
537              tory  in  addition  to  the  default  ones.   See  troff(1)  and
538              groff_font(5) for more details.
539

FILES

541       /usr/share/groff/1.20.1/font/devps/DESC
542              Device description file.
543
544       /usr/share/groff/1.20.1/font/devps/F
545              Font description file for font F.
546
547       /usr/share/groff/1.20.1/font/devps/download
548              List of downloadable fonts.
549
550       /usr/share/groff/1.20.1/font/devps/text.enc
551              Encoding used for text fonts.
552
553       /usr/share/groff/1.20.1/tmac/ps.tmac
554              Macros for use with grops; automatically loaded by troffrc
555
556       /usr/share/groff/1.20.1/tmac/pspic.tmac
557              Definition of PSPIC macro, automatically loaded by ps.tmac.
558
559       /usr/share/groff/1.20.1/tmac/psold.tmac
560              Macros to disable use of characters not present in  older  Post‐
561              Script printers (e.g., `eth' or `thorn').
562
563       /tmp/gropsXXXXXX
564              Temporary file.
565

SEE ALSO

567       afmtodit(1),     groff(1),    troff(1),    pfbtops(1),    groff_out(5),
568       groff_font(5), groff_char(7), groff_tmac(5)
569
570       PostScript  Language  Document  Structuring  Conventions  Specification
571http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf
572
573
574
575Groff Version 1.20.1            9 January 2009                        GROPS(1)
Impressum