1gropdf(1) General Commands Manual gropdf(1)
2
6 gropdf - groff output driver for Portable Document Format
7
9 gropdf [-dels] [-F font-directory] [-I inclusion-directory] [-p paper-
10 format] [-u [cmap-file]] [-y foundry] [file ...]
11 gropdf --help
13 gropdf -v
15 gropdf --version
16
18 The GNU roff PDF output driver translates the output of troff(1) into
19 Portable Document Format. Normally, gropdf is invoked by groff(1) when
20 the latter is given the “-T pdf” option. (In this installation, ps is
21 the default output device.) Use groff's -P option to pass any options
22 shown above to gropdf. If no file arguments are given, or if file is
23 “-”, gropdf reads the standard input stream. Output is written to the
24 standard output stream.
25 See section “Font installation” below for a guide to installing fonts
27 for gropdf.
28
30 --help displays a usage message, while -v and --version show version
31 information; all exit afterward.
32 -d Include debug information as comments within the PDF. Also pro‐
34 duces an uncompressed PDF.
35 -e Forces gropdf to embed all fonts (even the 14 base PDF fonts).
37 -F dir Prepend directory dir/devname to the search path for font, and
39 device description files; name is the name of the device, usu‐
40 ally pdf.
41 -I dir Search the directory dir for files named in \X'pdf: pdfpic' de‐
43 vice control commands. -I may be specified more than once; each
44 dir is searched in the given order. To search the current work‐
45 ing directory before others, add “-I .” at the desired place; it
46 is otherwise searched last.
47 -l Orient the document in landscape format.
49 -p paper-format
51 Set the physical dimensions of the output medium. This over‐
52 rides the papersize, paperlength, and paperwidth directives in
53 the DESC file; it accepts the same arguments as the papersize
54 directive. See groff_font(5) for details.
55 -s Append a comment line to end of PDF showing statistics, i.e.
57 number of pages in document. Ghostscript's ps2pdf complains
58 about this line if it is included, but works anyway.
59 -u [cmap-file]
61 gropdf normally includes a ToUnicode CMap with any font created
62 using text.enc as the encoding file, this makes it easier to
63 search for words which contain ligatures. You can include your
64 own CMap by specifying a cmap-file or have no CMap at all by
65 omitting the argument.
66 -y foundry
68 Set the foundry to use for selecting fonts of the same name.
69
71 The input to gropdf must be in the format output by troff(1). This is
72 described in groff_out(5). In addition, the device and font descrip‐
73 tion files for the device used must meet certain requirements: The res‐
74 olution must be an integer multiple of 72 times the sizescale. The pdf
75 device uses a resolution of 72000 and a sizescale of 1000.
76 The device description file must contain a valid paper format; see
78 groff_font(5). gropdf uses the same Type 1 Adobe PostScript fonts as
79 the grops device driver. Although the PDF Standard allows the use of
80 other font types (like TrueType) this implementation only accepts the
81 Type 1 PostScript font. Fewer Type 1 fonts are supported natively in
82 PDF documents than the standard 35 fonts supported by grops and all
83 PostScript printers, but all the fonts are available since any which
84 aren't supported natively are automatically embedded in the PDF.
85 gropdf supports the concept of foundries, that is different versions of
87 basically the same font. During install a Foundry file controls where
88 fonts are found and builds groff fonts from the files it discovers on
89 your system.
90 Each font description file must contain a command
92 internalname psname
94 which says that the PostScript name of the font is psname. Lines
96 starting with # and blank lines are ignored. The code for each charac‐
97 ter given in the font file must correspond to the code in the default
98 encoding for the font. This code can be used with the \N escape se‐
99 quence in troff to select the character, even if the character does not
100 have a groff name. Every character in the font file must exist in the
101 PostScript font, and the widths given in the font file must match the
102 widths used in the PostScript font.
103 Note that gropdf is currently only able to display the first 256 glyphs
105 in any font. This restriction will be lifted in a later version.
106 gropdf can automatically include the downloadable fonts necessary to
108 print the document. Fonts may be in PFA or PFB format.
109 Any downloadable fonts which should, when required, be included by
111 gropdf must be listed in the file /usr/share/groff/1.23.0/font/devpdf/
112 download; this should consist of lines of the form
113 foundry font filename
115 where foundry is the foundry name or blank for the default foundry.
117 font is the PostScript name of the font, and filename is the name of
118 the file containing the font; lines beginning with # and blank lines
119 are ignored; fields must be separated by tabs (spaces are not allowed);
120 filename is searched for using the same mechanism that is used for
121 groff font metric files. The download file itself is also sought using
122 this mechanism. Foundry names are usually a single character (such as
123 ‘U’ for the URW foundry) or empty for the default foundry. This de‐
124 fault uses the same fonts as ghostscript uses when it embeds fonts in a
125 PDF file.
126 In the default setup there are styles called R, I, B, and BI mounted at
128 font positions 1 to 4. The fonts are grouped into families A, BM, C,
129 H, HN, N, P, and T having members in each of these styles:
130 AR AvantGarde-Book
132 AI AvantGarde-BookOblique
133 AB AvantGarde-Demi
134 ABI AvantGarde-DemiOblique
135 BMR Bookman-Light
136 BMI Bookman-LightItalic
137 BMB Bookman-Demi
138 BMBI Bookman-DemiItalic
139 CR Courier
140 CI Courier-Oblique
141 CB Courier-Bold
142 CBI Courier-BoldOblique
143 HR Helvetica
144 HI Helvetica-Oblique
145 HB Helvetica-Bold
146 HBI Helvetica-BoldOblique
147 HNR Helvetica-Narrow
148 HNI Helvetica-Narrow-Oblique
149 HNB Helvetica-Narrow-Bold
150 HNBI Helvetica-Narrow-BoldOblique
151 NR NewCenturySchlbk-Roman
152 NI NewCenturySchlbk-Italic
153 NB NewCenturySchlbk-Bold
154 NBI NewCenturySchlbk-BoldItalic
155 PR Palatino-Roman
156 PI Palatino-Italic
157 PB Palatino-Bold
158 PBI Palatino-BoldItalic
159 TR Times-Roman
160 TI Times-Italic
161 TB Times-Bold
162 TBI Times-BoldItalic
163 There is also the following font which is not a member of a family:
165 ZCMI ZapfChancery-MediumItalic
167 There are also some special fonts called S for the PS Symbol font. The
169 lower case greek characters are automatically slanted (to match the
170 SymbolSlanted font (SS) available to PostScript). Zapf Dingbats is
171 available as ZD; the “hand pointing left” glyph (\[lh]) is available
172 since it has been defined using the \X'pdf: xrev' device control com‐
173 mand, which reverses the direction of letters within words.
174 The default color for \m and \M is black.
176 gropdf understands some of the device control commands supported by
178 grops(1).
179 \X'ps: invis'
181 Suppress output.
182 \X'ps: endinvis'
184 Stop suppressing output.
185 \X'ps: exec gsave currentpoint 2 copy translate n rotate neg exch neg
187 exch translate'
188 where n is the angle of rotation. This is to support the align
189 command in pic(1).
190 \X'ps: exec grestore'
192 Used by pic(1) to restore state after rotation.
193 \X'ps: exec n setlinejoin'
195 where n can be one of the following values.
196 0 = Miter join
198 1 = Round join
199 2 = Bevel join
200 \X'ps: exec n setlinecap'
202 where n can be one of the following values.
203 0 = Butt cap
205 1 = Round cap, and
206 2 = Projecting square cap
207 \X'ps: ... pdfmark'
209 All the pdfmark macros installed by using -m pdfmark or -m mspdf
210 (see documentation in pdfmark.pdf). A subset of these macros
211 are installed automatically when you use -Tpdf so you should not
212 need to use “-m pdfmark” to access most PDF functionality.
213 gropdf also supports a subset of the commands introduced in
215 present.tmac. Specifically it supports:-
216 PAUSE
218 BLOCKS
219 BLOCKE
220 Which allows you to create presentation type PDFs. Many of the other
222 commands are already available in other macro packages.
223 These commands are implemented with groff X commands:-
225 \X'ps: exec %%%%PAUSE'
227 The section before this is treated as a block and is introduced
228 using the current BLOCK transition setting (see “\X'pdf: transi‐
229 tion'” below). Equivalently, .pdfpause is available as a macro.
230 \X'ps: exec %%%%BEGINONCE'
232 Any text following this command (up to %%%%ENDONCE) is shown
233 only once, the next %%%%PAUSE will remove it. If producing a
234 non-presentation PDF, i.e. ignoring the pauses, see
235 GROPDF_NOSLIDE below, this text is ignored.
236 \X'ps: exec %%%%ENDONCE'
238 This terminates the block defined by %%%%BEGINONCE. This pair
239 of commands is what implements the .BLOCKS Once/.BLOCKE commands
240 in present.tmac.
241 The mom macro package already integrates these extensions, so you can
243 build slides with mom.
244 If you use present.tmac with gropdf there is no need to run the program
246 presentps(1) since the output will already be a presentation PDF.
247 All other ps: tags are silently ignored.
249 One \X device control command used by the DVI driver is also recog‐
251 nised.
252 \X'papersize=paper-format'
254 where the paper-format parameter is the same as that to the pa‐
255 persize directive. See groff_font(5). This means that you can
256 alter the page size at will within the PDF file being created by
257 gropdf. If you do want to change the paper format, it must be
258 done before you start creating the page.
259 gropdf supports several more device control features using the pdf:
261 tag. Some have counterpart convenience macros that take the same argu‐
262 ments and behave equivalently.
263 \X'pdf: pdfpic file alignment width height line-length'
265 Place an image of the specified width containing the PDF drawing
266 from file file of desired width and height (if height is missing
267 or zero then it is scaled proportionally). If alignment is -L
268 the drawing is left-aligned. If it is -C or -R a line-length
269 greater than the width of the drawing is required as well. If
270 width is specified as zero then the width is scaled in propor‐
271 tion to the height.
272 \X'pdf: xrev'
274 Toggle the reversal of glyph direction. This feature works
275 “letter by letter”, that is, each letter in a word is reversed
276 left-to-right, not the entire word. One application is the re‐
277 versal of glyphs in the Zapf Dingbats font. To restore the nor‐
278 mal glyph orientation, repeat the command.
279 \X'pdf: markstart /ANN-definition'
281 \X'pdf: markend'
282 Macros that support PDF bookmarks use these calls internally to
283 start and stop (respectively) the placement of the bookmark's
284 hot spot; the user will have called “.pdfhref L” with the text
285 of the hot spot. Normally, these are never used except from
286 within the pdfmark macros.
287 \X'pdf: marksuspend'
289 \X'pdf: markrestart'
290 If you use a page location trap to produce a header or footer,
291 or otherwise interrupt a document's text, you need to use these
292 commands if a PDF hot spot crosses a trap boundary; otherwise
293 any text output by the trap will be marked as part of the hot
294 spot. To prevent this error, place these device control com‐
295 mands or their corresponding convenience macros .pdfmarksuspend
296 and .pdfmarkrestart at the start and end of the trap macro, re‐
297 spectively.
298 \X'pdf: pagename name'
300 Assign the current page a name. All documents bear two default
301 names, ‘top’ and ‘bottom’. The convenience macro for this com‐
302 mand is .pdfpagename.
303 \X'pdf: switchtopage when name'
305 Normally each new page is appended to the end of the document,
306 this command allows following pages to be inserted at a ‘named’
307 position within the document (see pagename command above).
308 ‘when’ can be either ‘after’ or ‘before’. If it is omitted it
309 defaults to ‘before’. It should be used at the end of the page
310 before you want the switch to happen. This allows pages such as
311 a TOC to be moved to elsewhere in the document, but more eso‐
312 teric uses are possible. The convenience macro for this command
313 is .pdfswitchtopage.
314 \X'pdf: transition feature mode duration dimension motion direction
316 scale bool'
317 where feature can be either SLIDE or BLOCK. When it is SLIDE
318 the transition is used when a new slide is introduced to the
319 screen, if BLOCK then this transition is used for the individual
320 blocks which make up the slide.
321 mode is the transition type between slides:-
323 Split - Two lines sweep across the screen, revealing the
325 new page. The lines may be either horizontal or vertical
326 and may move inward from the edges of the page or outward
327 from the center, as specified by the dimension and motion
328 entries, respectively.
329 Blinds - Multiple lines, evenly spaced across the screen,
330 synchronously sweep in the same direction to reveal the
331 new page. The lines may be either horizontal or verti‐
332 cal, as specified by the dimension entry. Horizontal
333 lines move downward; vertical lines 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 duration is the length of the transition in seconds (default 1).
366 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 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 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 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 bool (Optional; PDF 1.5; Fly transition style only) If true, the
395 area that shall be flown in is rectangular and opaque.
396 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 Note: not all PDF Readers support any or all these transitions.
404 \X'pdf: background cmd left top right bottom weight'
406 \X'pdf: background off'
407 \X'pdf: background footnote bottom'
408 produces a background rectangle on the page, where
409 cmd is the command, which can be any of “page|fill|box” in
411 combination. Thus, “pagefill” would draw a rectangle
412 which covers the whole current page size (in which case
413 the rest of the parameters can be omitted because the box
414 dimensions are taken from the current media size). “box‐
415 fill”, on the other hand, requires the given dimensions
416 to place the box. Including “fill” in the command will
417 paint the rectangle with the current fill colour (as with
418 \M[]) and including “box” will give the rectangle a bor‐
419 der in the current stroke colour (as with \m[]).
420 cmd may also be “off” on its own, which will terminate
422 drawing the current box. If you have specified a page
423 colour with “pagefill”, it is always the first box in the
424 stack, and if you specify it again, it will replace the
425 first entry. Be aware that the “pagefill” box renders
426 the page opaque, so tools that “watermark” PDF pages are
427 unlikely to be successful. To return the background to
428 transparent, issue an “off” command with no other boxes
429 open.
430 Finally, cmd may be “footnote” followed by a new value
432 for bottom, which will be used for all open boxes on the
433 current page. This is to allow room for footnote areas
434 that grow while a page is processed (to accommodate mul‐
435 tiple footnotes, for instance). (If the value is nega‐
436 tive, it is used as an offset from the bottom of the
437 page.)
438 left
440 top
441 right
442 bottom are the coordinates of the box. The top and bottom coor‐
443 dinates are the minimum and maximum for the box, since
444 the actual start of the box is groff's drawing position
445 when you issue the command, and the bottom of the box is
446 the point where you turn the box “off”. The top and bot‐
447 tom coordinates are used only if the box drawing extends
448 onto the next page; ordinarily, they would be set to the
449 header and footer margins.
450 weight provides the line width for the border if “box” is in‐
452 cluded in the command.
453 The convenience macro for this escape sequence is .pdfback‐
455 ground. An sboxes macro file is also available; see
456 groff_tmac(5).
457 Macros
459 gropdf's support macros in pdf.tmac define the convenience macros de‐
460 scribed above. Some features have no direct device control command
461 counterpart.
462 .pdfinfo /field content ...
464 Define PDF metadata. field may be be one of Title, Author, Sub‐
465 ject, Keywords, or another datum supported by the PDF standard
466 or your reader. field must be prefixed with a slash.
467 Importing graphics
469 gropdf supports only the inclusion of other PDF files for inline im‐
470 ages. Such a PDF file may, however, contain any of the graphic formats
471 supported by the PDF standard, such as JPEG/JFIF, PNG, and GIF. Any
472 application that outputs PDF can thus be used to prepare files for em‐
473 bedding in documents processed by groff and gropdf.
474 The PDF file you wish to insert must be a single page and the drawing
476 must just fit inside the media size of the PDF file. In inkscape(1) or
477 gimp(1), for example, make sure the canvas size just fits the image.
478 The PDF parser gropdf implements has not been rigorously tested with
480 all applications that produce PDF. If you find a single-page PDF which
481 fails to import properly, try processing it with the pdftk(1) program.
482 pdftk existing-file output new-file
483 You may find that new-file imports successfully.
484 TrueType and other font formats
486 gropdf does not yet support any font formats besides Adobe Type 1 (PFA
487 or PFB).
488
490 The following is a step-by-step font installation guide for gropdf.
491 • Convert your font to something groff understands. This is a Post‐
493 Script Type 1 font in PFA or PFB format, together with an AFM file.
494 A PFA file begins as follows.
495 %!PS-AdobeFont-1.0:
496 A PFB file contains this string as well, preceded by some non-print‐
497 ing bytes. In the following steps, we will consider the use of
498 CTAN's BrushScriptX-Italic ⟨https://ctan.org/tex-archive/fonts/
499 brushscr⟩ font in PFA format.
500 • Convert the AFM file to a groff font description file with the
502 afmtodit(1) program. For instance,
503 $ afmtodit BrushScriptX-Italic.afm text.map BSI
504 converts the Adobe Font Metric file BrushScriptX-Italic.afm to the
505 groff font description file BSI.
506 If you have a font family which provides regular upright (roman),
508 bold, italic, and bold-italic styles, (where “italic” may be
509 “oblique” or “slanted”), we recommend using R, B, I, and BI, respec‐
510 tively, as suffixes to the groff font family name to enable groff's
511 font family and style selection features. An example is groff's
512 built-in support for Times: the font family name is abbreviated as T,
513 and the groff font names are therefore TR, TB, TI, and TBI. In our
514 example, however, the BrushScriptX font is available in a single
515 style only, italic.
516 • Install the groff font description file(s) in a devpdf subdirectory
518 in the search path that groff uses for device and font file descrip‐
519 tions. See the GROFF_FONT_PATH entry in section “Environment” of
520 troff(1) for the current value of the font search path. While groff
521 doesn't directly use AFM files, it is a good idea to store them
522 alongside its font description files.
523 • Register fonts in the devpdf/download file so they can be located for
525 embedding in PDF files gropdf generates. Only the first download
526 file encountered in the font search path is read. If in doubt, copy
527 the default download file (see section “Files” below) to the first
528 directory in the font search path and add your fonts there. The
529 PostScript font name used by gropdf is stored in the internalname
530 field in the groff font description file. (This name does not neces‐
531 sarily resemble the font's file name.) If the font in our example
532 had originated from a foundry named Z, we would add the following
533 line to download.
534 Z→BrushScriptX-Italic→BrushScriptX-Italic.pfa
535 A tab character, depicted as →, separates the fields. The default
536 foundry has no name: its field is empty and entries corresponding to
537 it start with a tab character, as will the one in our example.
538 • Test the selection and embedding of the new font.
540 printf "\\f[BSI]Hello, world!\n" | groff -T pdf -P -e >hello.pdf
541 see hello.pdf
542
544 GROFF_FONT_PATH
545 A list of directories in which to seek the selected output de‐
546 vice's directory of device and font description files. If, in
547 the download file, the font file has been specified with a full
548 path, no directories are searched. See troff(1) and
549 groff_font(5).
550 GROPDF_NOSLIDE
552 If set and evaluates to a true value (to Perl), gropdf ignores
553 commands specific to presentation PDFs, producing a normal PDF
554 instead.
555 SOURCE_DATE_EPOCH
557 A timestamp (expressed as seconds since the Unix epoch) to use
558 as the output creation timestamp in place of the current time.
559 The time is converted to human-readable form using Perl's
560 localtime() function and recorded in a PDF comment.
561 TZ The time zone to use when converting the current time (or value
563 of SOURCE_DATE_EPOCH) to human-readable form; see tzset(3).
564
566 /usr/share/groff/1.23.0/font/devpdf/DESC
567 describes the pdf output device.
568 /usr/share/groff/1.23.0/font/devpdf/F
570 describes the font known as F on device pdf.
571 /usr/share/groff/1.23.0/font/devpdf/U-F
573 describes the font from the URW foundry (versus the Adobe de‐
574 fault) known as F on device pdf.
575 /usr/share/groff/1.23.0/font/devpdf/download
577 lists fonts available for embedding within the PDF document (by
578 analogy to the ps device's downloadable font support).
579 /usr/share/groff/1.23.0/font/devpdf/Foundry
581 is a data file used by the groff build system to locate Post‐
582 Script Type 1 fonts.
583 /usr/share/groff/1.23.0/font/devpdf/enc/text.enc
585 describes the encoding scheme used by most PostScript Type 1
586 fonts; the encoding directive of font description files for the
587 pdf device refers to it.
588 /usr/share/groff/1.23.0/tmac/pdf.tmac
590 defines macros for use with the pdf output device. It is auto‐
591 matically loaded by troffrc when the pdf output device is se‐
592 lected.
593 /usr/share/groff/1.23.0/tmac/pdfpic.tmac
595 defines the PDFPIC macro for embedding images in a document; see
596 groff_tmac(5). It is automatically loaded by troffrc.
597
599 gropdf was written and is maintained by Deri James ⟨deri@chuzzlewit
600 .myzen.co.uk⟩.
601
603 /usr/share/doc/groff/sboxes/msboxes.ms
604 /usr/share/doc/groff/sboxes/msboxes.pdf
605 “Using PDF boxes with groff and the ms macros”, by Deri James.
606 present.tmac
608 is part of gpresent ⟨https://bob.diertens.org/corner/useful/
609 gpresent/⟩, a software package by Bob Diertens that works with
610 groff to produce presentations (“foils”, or “slide decks”).
611 afmtodit(1), groff(1), troff(1), groff_font(5), groff_out(5)
613groff 1.23.0 2 November 2023 gropdf(1)