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] [file ...]
11

DESCRIPTION

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

OPTIONS

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

USAGE

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

FONT INSTALLATION

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

OLD FONTS

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

ENVIRONMENT

528       GROPS_PROLOGUE
529              If this is set to foo, then grops uses the file foo (in the font
530              path) instead of the default prologue file prologue.  The option
531              -P overrides this environment variable.
532
533       GROFF_FONT_PATH
534              A  list of directories in which to search for the devname direc‐
535              tory  in  addition  to  the  default  ones.   See  troff(1)  and
536              groff_font(5) for more details.
537
538       SOURCE_DATE_EPOCH
539              A  timestamp  (expressed as seconds since the Unix epoch) to use
540              as the creation timestamp in place of the current time.
541

FILES

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

SEE ALSO

570       afmtodit(1),    groff(1),    troff(1),    pfbtops(1),     groff_out(5),
571       groff_font(5), groff_char(7), groff_tmac(5)
572
573       PostScript  Language  Document  Structuring  Conventions  Specification
574http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf
575
576
577
578groff 1.22.4                     22 July 2021                         GROPS(1)
Impressum