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
51              papersize,  paperlength,  and  paperwidth  commands  in the DESC
52              file; it accepts the same arguments as  the  papersize  command.
53              See 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]  Gropdf normally includes a ToUnicode CMap with any
60              font created using text.enc as the encoding file, this makes  it
61              easier  to  search  for  words which contain ligatures.  You can
62              include your own CMap by specifying a cmapfile or have  no  CMap
63              at all by omitting the argument.
64
65       -v
66       --version
67              Print the version number and exit.
68
69       -y foundry
70              Set the foundry to use for selecting fonts of the same name.
71

USAGE

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

FONT INSTALLATION

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

ENVIRONMENT

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

FILES

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

SEE ALSO

515       afmtodit(1), groff(1), troff(1), groff_font(5), groff_out(5)
516
517
518
519groff 1.22.4                    3 November 2020                      GROPDF(1)
Impressum