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

NAME

6       gropdf - PDF driver for groff
7

SYNOPSIS

9       gropdf [-dels] [-F dir] [-I dir] [-p paper-size] [-u [cmapfile]]
10              [-y foundry] [file ...]
11
12       gropdf -v
13       gropdf --version
14

DESCRIPTION

16       gropdf translates the output of GNU  troff  to  PDF.   Normally  gropdf
17       should  be  invoked by using the groff command with a -Tpdf option.  If
18       no files are given, gropdf reads the standard input.  A filename  of  -
19       also  causes  gropdf to read the standard input.  PDF output is written
20       to the standard output.  When gropdf is run by  groff  options  can  be
21       passed to gropdf using groff's -P option.
22
23       See  section “Font Installation” below for a guide how to install fonts
24       for gropdf.
25

OPTIONS

27       Whitespace is permitted between a command-line option and its argument.
28
29       -d     Include debug information as comments within the PDF.  Also pro‐
30              duces an uncompressed PDF.
31
32       -e     Forces gropdf to embed all fonts (even the 14 base PDF fonts).
33
34       -F dir Prepend  directory  dir/devname to the search path for font, and
35              device description files; name is the name of the  device,  usu‐
36              ally pdf.
37
38       -I dir This  option  may  be used to add a directory to the search path
39              for files named in \X'pdf: pdfpic' escape.  The  current  direc‐
40              tory  is  always  searched  first.  This option may be specified
41              more than once; the directories are then searched in  the  order
42              specified.
43
44              No directory search is performed for files with an absolute file
45              name.
46
47       -l     Orient the document in landscape format.
48
49       -p paper-size
50              Set physical dimension of output medium.  This overrides the pa‐
51              persize,  paperlength, and paperwidth commands in the DESC file;
52              it accepts the same arguments as  the  papersize  command.   See
53              groff_font(5) for details.
54
55       -s     Append  a  comment  line  to end of PDF showing statistics, i.e.
56              number of pages in  document.   Ghostscript's  ps2pdf  complains
57              about this line if it is included, but works anyway.
58
59       -u [cmapfile]
60              Gropdf  normally includes a ToUnicode CMap with any font created
61              using text.enc as the encoding file, this  makes  it  easier  to
62              search  for words which contain ligatures.  You can include your
63              own CMap by specifying a cmapfile or have  no  CMap  at  all  by
64              omitting the argument.
65
66       -v
67       --version
68              Print the version number and exit.
69
70       -y foundry
71              Set the foundry to use for selecting fonts of the same name.
72

USAGE

74       The  input to gropdf must be in the format output by troff(1).  This is
75       described in groff_out(5).
76
77       In addition, the device and font description files for the device  used
78       must  meet certain requirements: The resolution must be an integer mul‐
79       tiple of 72 times the sizescale.  The pdf device uses a  resolution  of
80       72000 and a sizescale of 1000.
81
82       The  device  description  file  must  contain  a  valid paper size; see
83       groff_font(5) for more information.  gropdf uses the same Type 1  Adobe
84       PostScript fonts as the grops device driver.  Although the PDF Standard
85       allows the use of other font types (like TrueType) this  implementation
86       only  accepts  the Type 1 PostScript font.  Fewer Type 1 fonts are sup‐
87       ported natively in PDF documents than the standard 35  fonts  supported
88       by  grops  and all PostScript printers, but all the fonts are available
89       since any which aren't supported natively are automatically embedded in
90       the PDF.
91
92       gropdf supports the concept of foundries, that is different versions of
93       basically the same font.  During install a Foundry file controls  where
94       fonts  are  found and builds groff fonts from the files it discovers on
95       your system.
96
97       Each font description file must contain a command
98
99              internalname psname
100
101       which says that the PostScript name  of  the  font  is  psname.   Lines
102       starting with # and blank lines are ignored.  The code for each charac‐
103       ter given in the font file must correspond to the code in  the  default
104       encoding  for  the  font.  This code can be used with the \N escape se‐
105       quence in troff to select the character, even if the character does not
106       have  a groff name.  Every character in the font file must exist in the
107       PostScript font, and the widths given in the font file must  match  the
108       widths used in the PostScript font.
109
110       Note that gropdf is currently only able to display the first 256 glyphs
111       in any font.  This restriction will be lifted in a later version.
112
113       gropdf can automatically include the downloadable  fonts  necessary  to
114       print the document.  Fonts may be in PFA or PFB format.
115
116       Any  downloadable  fonts  which  should,  when required, be included by
117       gropdf must be  listed  in  the  file  /usr/share/groff/1.22.4/font/de‐
118       vpdf/download; this should consist of lines of the form
119
120              foundry font filename
121
122       where  foundry  is  the  foundry name or blank for the default foundry.
123       font is the PostScript name of the font, and filename is  the  name  of
124       the  file  containing  the font; lines beginning with # and blank lines
125       are ignored; fields must be separated by tabs (spaces are not allowed);
126       filename  is  searched  for  using  the same mechanism that is used for
127       groff font metric files.  The download file itself is also searched for
128       using  this mechanism; currently, only the first found file in the font
129       path is used.  Foundry names are usually a single  character  (such  as
130       ‘U’  for  the  URW Foundry) or blank for the default foundry.  This de‐
131       fault uses the same fonts as ghostscript uses when it embeds fonts in a
132       PDF file.
133
134       In the default setup there are styles called R, I, B, and BI mounted at
135       font positions 1 to 4.  The fonts are grouped into families A,  BM,  C,
136       H, HN, N, P, and T having members in each of these styles:
137
138              AR     AvantGarde-Book
139              AI     AvantGarde-BookOblique
140              AB     AvantGarde-Demi
141              ABI    AvantGarde-DemiOblique
142              BMR    Bookman-Light
143              BMI    Bookman-LightItalic
144              BMB    Bookman-Demi
145              BMBI   Bookman-DemiItalic
146              CR     Courier
147              CI     Courier-Oblique
148              CB     Courier-Bold
149              CBI    Courier-BoldOblique
150              HR     Helvetica
151              HI     Helvetica-Oblique
152              HB     Helvetica-Bold
153              HBI    Helvetica-BoldOblique
154              HNR    Helvetica-Narrow
155              HNI    Helvetica-Narrow-Oblique
156              HNB    Helvetica-Narrow-Bold
157              HNBI   Helvetica-Narrow-BoldOblique
158              NR     NewCenturySchlbk-Roman
159              NI     NewCenturySchlbk-Italic
160              NB     NewCenturySchlbk-Bold
161              NBI    NewCenturySchlbk-BoldItalic
162              PR     Palatino-Roman
163              PI     Palatino-Italic
164              PB     Palatino-Bold
165              PBI    Palatino-BoldItalic
166              TR     Times-Roman
167              TI     Times-Italic
168              TB     Times-Bold
169              TBI    Times-BoldItalic
170
171       There is also the following font which is not a member of a family:
172
173              ZCMI   ZapfChancery-MediumItalic
174
175       There are also some special fonts called S for the PS Symbol font.  The
176       lower case greek characters are automatically  slanted  (to  match  the
177       SymbolSlanted  font  (SS)  available  to PostScript).  Zapf Dingbats is
178       available as ZD, the "hand pointing left" glyph  (\[lh])  is  available
179       since  it  has been defined using the \X'pdf: xrev' extension which re‐
180       verses the direction of letters within words.
181
182       The default color for \m and \M is black.
183
184       gropdf understands some of the X commands produced using the \X  escape
185       sequences  supported  by  grops.   Specifically,  the following is sup‐
186       ported.
187
188       \X'ps: invis'
189              Suppress output.
190
191       \X'ps: endinvis'
192              Stop suppressing output.
193
194       \X'ps: exec gsave currentpoint 2 copy translate n rotate neg  exch  neg
195       exch translate'
196              where  n is the angle of rotation.  This is to support the align
197              command in gpic.
198
199       \X'ps: exec grestore'
200              Again used by gpic to restore after rotation.
201
202       \X'ps: exec n setlinejoin'
203              where n can be one of the following values.
204
205              0 = Miter join
206              1 = Round join
207              2 = Bevel join
208
209       \X'ps: exec n setlinecap'
210              where n can be one of the following values.
211
212              0 = Butt cap
213              1 = Round cap, and
214              2 = Projecting square cap
215
216       \X'ps: ... pdfmark'
217              All the pdfmark macros installed by using -m pdfmark or -m mspdf
218              (see  documentation  in  pdfmark.pdf).  A subset of these macros
219              are installed automatically when you use -Tpdf so you should not
220              need  to  use ‘-m pdfmark’ for using most of the PDF functional‐
221              ity.
222
223       gropdf  also  supports  a  subset  of  the   commands   introduced   in
224       present.tmac.  Specifically it supports:-
225
226              PAUSE
227              BLOCKS
228              BLOCKE
229
230       Which  allows  you to create presentation type PDFs.  Many of the other
231       commands are already available in other macro packages.
232
233       These commands are implemented with groff X commands:-
234
235       \X'ps: exec %%%%PAUSE
236              The section before this is treated as a block and is  introduced
237              using  the  current  BLOCK transition setting (see ‘pdf: transi‐
238              tion’ below).  This command can be introduced  using  the  macro
239              .pdfpause.
240
241       \X'ps: exec %%%%BEGINONCE
242              Any  text  following  this  command (up to %%%%ENDONCE) is shown
243              only once, the next %%%%PAUSE will remove it.   If  producing  a
244              non   presentation   pdf,   i.e.   ignoring   the   pauses,  see
245              GROPDF_NOSLIDE below, this text is ignored.
246
247       \X'ps: exec %%%%ENDONCE
248              This terminates the block defined by %%%%BEGINONCE.   This  pair
249              of commands is what implements the .BLOCKS Once/.BLOCKE commands
250              in present.tmac.
251
252       The mom macro set already has integration with these extensions so  you
253       can build slides with mom.
254
255       If you use present.tmac with gropdf there is no need to run the program
256       presentps(1) since the output will already be a presentation pdf.
257
258       All other ps: tags are silently ignored.
259
260       One \X special used by the DVI driver is also recognised:
261
262       \X'papersize=paper-size'
263              where the paper-size parameter is the same as the papersize com‐
264              mand.   See  groff_font(5) for details.  This means that you can
265              alter the page size at will within the PDF file being created by
266              gropdf.   If  you  do  want to change the paper size, it must be
267              done before you start creating the page.
268
269       In addition, gropdf supports its own suite of pdf: tags.  The following
270       tags are supported:
271
272       \X'pdf: pdfpic file alignment width height line-length'
273              Place an image of the specified width containing the PDF drawing
274              from file file of desired width and height (if height is missing
275              or  zero  then it is scaled proportionally).  If alignment is -L
276              the drawing is left aligned.  If it is -C  or  -R  a  linelength
277              greater  than  the width of the drawing is required as well.  If
278              width is specified as zero then the width is scaled  in  propor‐
279              tion to the height.
280
281       \X'pdf: xrev'
282              This  toggles  a  flag  which reverses the direction of printing
283              letter by letter, i.e., each separate letter  is  reversed,  not
284              the  entire word.  This is useful for reversing the direction of
285              glyphs in the Dingbats font.  To return to normal  printing  re‐
286              peat the command again.
287
288       \X'pdf: markstart /ANN definition'
289              The  macros which support PDF Bookmarks use this call internally
290              to start the definition of  bookmark  hotspot  (user  will  have
291              called  ‘.pdfhref  L’  with  the text which will become the ‘hot
292              spot’ region).  Normally this is never used except  from  within
293              the pdfmark macros.
294
295       \X'pdf: markend'
296              The  macros which support PDF Bookmarks use this call internally
297              to stop the definition  of  bookmark  hotspot  (user  will  have
298              called  ‘.pdfhref  L’  with  the text which will become the ‘hot
299              spot’ region).  Normally this is never used except  from  within
300              the pdfmark macros.
301
302       \X'pdf: marksuspend'
303       \X'pdf: markrestart'
304              If you are using page traps to produce headings, footings, etc.,
305              you need to use these in case a ‘hot spot’ crosses a page bound‐
306              ary,  otherwise  any text output by the heading or footing macro
307              will be marked as part of the ‘hot spot’.  To stop this  happen‐
308              ing  just  place  ‘.pdfmarksuspend’ and ‘.pdfmarkrestart’ at the
309              start and end of the page trap macro, respectively.  (These  are
310              just  convenience  macros  which emit the \X code.  These macros
311              must only be used within page traps.)
312
313       \X'pdf: transition'feature mode  duration  dimension  motion  direction
314       scale bool
315              where
316
317              feature  can  be  either  SLIDE  or BLOCK.  When it is SLIDE the
318              transition is used when a new slide is introduced to the screen,
319              if  BLOCK then this transition is used for the individual blocks
320              which make up the slide.
321              mode is the transition type between slides:-
322
323                     Split - Two lines sweep across the screen, revealing  the
324                     new page.  The lines may be either horizontal or vertical
325                     and may move inward from the edges of the page or outward
326                     from the center, as specified by the dimension and motion
327                     entries, respectively.
328                     Blinds - Multiple lines, evenly spaced across the screen,
329                     synchronously  sweep  in the same direction to reveal the
330                     new page.  The lines may be either horizontal  or  verti‐
331                     cal, as specified by the dimension
332                      entry.   Horizontal  lines move downward; vertical lines
333                     move to the right.
334                     Box - A rectangular box sweeps inward from the  edges  of
335                     the  page or outward from the center, as specified by the
336                     motion entry, revealing the new page.
337                     Wipe - A single line sweeps across the  screen  from  one
338                     edge  to  the other in the direction specified by the di‐
339                     rection entry, revealing the new page.
340                     Dissolve - The old page dissolves gradually to reveal the
341                     new one.
342                     Glitter  -  Similar  to  Dissolve, except that the effect
343                     sweeps across the page in a wide  band  moving  from  one
344                     side  of  the screen to the other in the direction speci‐
345                     fied by the direction entry.
346                     R - The new page simply replaces the old one with no spe‐
347                     cial  transition effect; the direction entry shall be ig‐
348                     nored.
349                     Fly - (PDF 1.5) Changes are flown out or in (as specified
350                     by  motion),  in the direction specified by direction, to
351                     or from a location that is offscreen except  when  direc‐
352                     tion is None.
353                     Push - (PDF 1.5) The old page slides off the screen while
354                     the new page slides in, pushing the old page out  in  the
355                     direction specified by direction.
356                     Cover - (PDF 1.5) The new page slides on to the screen in
357                     the direction specified by direction,  covering  the  old
358                     page.
359                     Uncover - (PDF 1.5) The old page slides off the screen in
360                     the direction specified by direction, uncovering the  new
361                     page in the direction specified by direction.
362                     Fade  -  (PDF 1.5) The new page gradually becomes visible
363                     through the old one.
364
365              duration is the length of the transition in seconds (default 1).
366
367              dimension (Optional; Split and Blinds  transition  styles  only)
368              The dimension in which the specified transition effect shall oc‐
369              cur: H Horizontal, or V Vertical.
370
371              motion (Optional; Split, Box and Fly transition styles only) The
372              direction  of  motion for the specified transition effect: I In‐
373              ward from the edges of the page, or O Outward from the center of
374              the page.
375
376              direction (Optional; Wipe, Glitter, Fly, Cover, Uncover and Push
377              transition styles only) The direction  in  which  the  specified
378              transition  effect  shall  moves,  expressed in degrees counter‐
379              clockwise starting from a left-to-right direction.  If the value
380              is  a number, it shall be one of: 0 = Left to right, 90 = Bottom
381              to top (Wipe only), 180 = Right to left (Wipe only), 270  =  Top
382              to  bottom,  315  =  Top-left to bottom-right (Glitter only) The
383              value can be None, which is relevant only for the Fly transition
384              when the value of scale is not 1.0.
385
386              scale  (Optional; PDF 1.5; Fly transition style only) The start‐
387              ing or ending scale at which the changes shall be drawn.  If mo‐
388              tion  specifies  an  inward transition, the scale of the changes
389              drawn shall progress from scale to 1.0 over the  course  of  the
390              transition.   If  motion  specifies  an  outward transition, the
391              scale of the changes drawn shall progress from 1.0 to scale over
392              the course of the transition
393
394              bool (Optional; PDF 1.5; Fly transition style only) If true, the
395              area that shall be flown in is rectangular and opaque.
396
397              This command can be used by calling the macro .pdftransition us‐
398              ing  the  parameters described above.  Any of the parameters may
399              be replaced with a "." which signifies the parameter retains its
400              previous  value,  also  any  trailing missing parameters are ig‐
401              nored.
402
403              Note: not all PDF Readers support any or all these transitions.
404
405   Importing graphics
406       gropdf only supports importing other PDF files as graphics.   But  that
407       PDF  file  may  contain any of the graphic formats supported by the PDF
408       standard (such as JPEG, PNG, GIF, etc.).  So any application which out‐
409       puts  PDF  can be used as an embedded file in gropdf.  The PDF file you
410       wish to insert must be a single page and the drawing must just fit  in‐
411       side  the  media  size  of the PDF file.  So, in inkscape(1) or gimp(1)
412       (for example) make sure the canvas size just fits the image.
413
414       The PDF parser used in gropdf has not been rigorously tested  with  all
415       possible  applications  which  produce PDFs.  If you find a single page
416       PDF which fails to import properly, it is worth running it through  the
417       pdftk(1) program by issuing the command:
418
419              pdftk oldfile.pdf output newfile.pdf
420
421       You may find that newfile.pdf will now load successfully.
422
423   TrueType and other font formats
424       gropdf  does  not  support  any other fonts except Adobe Type 1 (PFA or
425       PFB).
426

FONT INSTALLATION

428       This section gives a summary of the above explanations; it can serve as
429       a step-by-step font installation guide for gropdf.
430
431        •  Convert your font to something groff understands.  This is either a
432           PostScript Type 1 font in either PFA or PFB, together with  an  AFM
433           file.
434
435           The very first line in a PFA/PFB file contains this:
436
437                  %!PS-AdobeFont-1.0:
438
439           A  PFB file has this also in the first line, but the string is pre‐
440           ceded with some binary bytes.
441
442        •  Convert the AFM file to a groff  font  description  file  with  the
443           afmtodit(1) program.  An example call is
444
445                  afmtodit Foo-Bar-Bold.afm map/textmap FBB
446
447           which converts the metric file ‘Foo-Bar-Bold.afm’ to the groff font
448           ‘FBB’.  If you have a font family which comes  with  normal,  bold,
449           italic, and bold italic faces, it is recommended to use the letters
450           R, B, I, and BI, respectively, as postfixes in the groff font names
451           to  make groff's ‘.fam’ request work.  An example is groff's built-
452           in Times-Roman font: The font family name is T, and the groff  font
453           names are TR, TB, TI, and TBI.
454
455        •  Install  both  the  groff font description files and the fonts in a
456           ‘devpdf’ subdirectory of the font path which groff finds.  See sec‐
457           tion  “Environment”  in  troff(1)  for the actual value of the font
458           path.  Note that groff doesn't use the AFM files (but it is a  good
459           idea to store them anyway).
460
461        •  Register  all  fonts which must be downloaded to the printer in the
462           devpdf/download file.  Only the first occurrence of  this  file  in
463           the font path is read.  This means that you should copy the default
464           download file to the first directory in your font path and add your
465           fonts  there.   To continue the above example we assume that the PS
466           font name for Foo-Bar-Bold.pfa is ‘XY-Foo-Bar-Bold’  (the  PS  font
467           name  is  stored in the internalname field in the FBB file) and be‐
468           longs to foundry ‘F’ thus the following line  should  be  added  to
469           download:
470
471                  F XY-Foo-Bar-Bold Foo-Bar-Bold.pfa
472
473           Use a tab character to separate the fields, and the ‘foundry’ field
474           should be null for the default foundry.
475

ENVIRONMENT

477       GROFF_FONT_PATH
478              A list of directories in which to search for the devname  direc‐
479              tory in addition to the default ones.  If, in the download file,
480              the font file has been specified with a full path,  no  directo‐
481              ries  are searched.  See troff(1) and groff_font(5) for more de‐
482              tails.
483
484       GROPDF_NOSLIDE
485              If this is set true, gropdf will ignore all commands which  pro‐
486              duce a presentation pdf, and produce a normal pdf instead.
487
488       SOURCE_DATE_EPOCH
489              A  timestamp  (expressed as seconds since the Unix epoch) to use
490              as the creation timestamp in place of the current time.
491

FILES

493       /usr/share/groff/1.22.4/font/devpdf/DESC
494              Device description file.
495
496       /usr/share/groff/1.22.4/font/devpdf/F
497              Font description file for font F.
498
499       /usr/share/groff/1.22.4/font/devpdf/U-F
500              Font description file for font F (using foundry  U  rather  than
501              the default foundry).
502
503       /usr/share/groff/1.22.4/font/devpdf/download
504              List of downloadable fonts.
505
506       /usr/share/groff/1.22.4/font/devpdf/Foundry
507              A Perl script used during install to locate suitable fonts.
508
509       /usr/share/groff/1.22.4/font/devpdf/enc/text.enc
510              Encoding used for text fonts.
511
512       /usr/share/groff/1.22.4/tmac/pdf.tmac
513              Macros for use with gropdf; automatically loaded by troffrc.
514

SEE ALSO

516       afmtodit(1), groff(1), troff(1), groff_font(5), groff_out(5)
517
518
519
520groff 1.22.4                    19 January 2023                      GROPDF(1)
Impressum