Debian Codegraph @

upstream/opensuse-tumbleweed/man1/pdfroff.1

raw
1 .TH pdfroff 1 "2 March 2026" "groff 1.23.0"
2 .SH Name
3 pdfroff \- construct files in Portable Document Format using
4 .I groff
5 .
6 .
7 .\" ====================================================================
8 .\" Legal Terms
9 .\" ====================================================================
10 .\"
11 .\" Copyright (C) 2005-2020 Free Software Foundation, Inc.
12 .\"
13 .\" This file is part of groff, the GNU roff type-setting system.
14 .\"
15 .\" Permission is granted to copy, distribute and/or modify this
16 .\" document under the terms of the GNU Free Documentation License,
17 .\" Version 1.3 or any later version published by the Free Software
18 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
19 .\" and with no Back-Cover Texts.
20 .\"
21 .\" A copy of the Free Documentation License is included as a file
22 .\" called FDL in the main directory of the groff source package.
23 .
24 .
25 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
26 .do nr *groff_pdfroff_1_man_C \n[.cp]
27 .cp 0
28 .
29 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
30 .nr do-fallback 0
31 .if !\n(.f .nr do-fallback 1 \" mandoc
32 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
33 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
34 .if \n[do-fallback] \{\
35 . de MR
36 . ie \\n(.$=1 \
37 . I \%\\$1
38 . el \
39 . IR \%\\$1 (\\$2)\\$3
40 . .
41 .\}
42 .rr do-fallback
43 .
44 .
45 .\" ====================================================================
46 .SH Synopsis
47 .\" ====================================================================
48 .
49 .SY pdfroff
50 .RI [ groff-option ]
51 .RB [ \-\-emit\-ps ]
52 .RB [ \-\-no\-toc\-relocation ]
53 .RB [ \-\-no\-kill\-null\-pages ]
54 .RB [ \-\-stylesheet=\c
55 .IR name ]
56 .RB [ \-\-no\-pdf\-output ]
57 .RB [ \-\-pdf\-output=\c
58 .IR name ]
59 .RB [ \-\-no\-reference\-dictionary ]
60 .RB [ \-\-reference\-dictionary=\c
61 .IR name ]
62 .RB [ \-\-report\-progress ]
63 .RB [ \-\-keep\-temporary\-files ]
64 .RI [ file\~ .\|.\|.]
65 .YS
66 .
67 .
68 .SY pdfroff
69 .B \-h
70 .
71 .SY pdfroff
72 .B \-\-help
73 .YS
74 .
75 .
76 .SY pdfroff
77 .B \-v
78 .RI [ groff-option
79 \&.\|.\|.\&]
80 .
81 .SY pdfroff
82 .B \-\-version
83 .RI [ groff-option
84 \&.\|.\|.\&]
85 .YS
86 .
87 .
88 .P
89 .I groff-option
90 is any short option supported by
91 .MR groff 1
92 except for
93 .BR \-h ,
94 .BR \-T ,
95 and
96 .BR \-v ;
97 see section \[lq]Usage\[rq] below.
98 .
99 .
100 .\" ====================================================================
101 .SH Description
102 .\" ====================================================================
103 .
104 .I pdfroff
105 is a wrapper program for the GNU text processing system,
106 .IR groff .
107 .
108 It transparently handles the mechanics of multiple pass
109 .I groff
110 processing,
111 when applied to suitably marked up
112 .I groff
113 source files,
114 such that tables of contents and body text are formatted separately,
115 and are subsequently combined in the correct order,
116 for final publication as a single PDF document.
117 .
118 A further optional \[lq]style sheet\[rq] capability is provided;
119 this allows for the definition of content which is required to precede
120 the table of contents,
121 in the published document.
122 .
123 .
124 .P
125 For each invocation of
126 .IR pdfroff ,
127 the ultimate
128 .I groff
129 output stream is post-processed by the Ghostscript
130 .MR gs 1
131 interpreter to produce a finished PDF document.
132 .
133 .
134 .P
135 .I pdfroff
136 makes no assumptions about,
137 and imposes no restrictions on,
138 the use of any
139 .I groff
140 macro packages which the user may choose to employ,
141 in order to achieve a desired document format;
142 however,
143 it
144 .I does
145 include specific built in support for the
146 .I \%pdfmark
147 macro package,
148 should the user choose to employ it.
149 .
150 Specifically,
151 if the
152 .I pdfhref
153 macro,
154 defined in the
155 .I \%pdfmark.tmac
156 package,
157 is used to define public reference marks,
158 or dynamic links to such reference marks,
159 then
160 .I pdfroff
161 performs as many preformatting
162 .I groff
163 passes as required,
164 up to a maximum limit of
165 .IR four ,
166 in order to compile a document reference dictionary,
167 to resolve
168 references,
169 and to expand the dynamically defined content of links.
170 .
171 .
172 .\" ====================================================================
173 .SH Usage
174 .\" ====================================================================
175 .
176 The command line is parsed in accordance with normal GNU conventions,
177 but with one exception\(emwhen specifying any short form option
178 (i.e.,
179 a single character option introduced by a single hyphen),
180 and if that option expects an argument,
181 then it
182 .I must
183 be specified independently
184 (i.e.,
185 it may
186 .I not
187 be appended to any group of other single character short form options).
188 .
189 .
190 .P
191 Long form option names
192 (i.e.,
193 those introduced by a double hyphen)
194 may
195 be abbreviated to their minimum length unambiguous initial substring.
196 .
197 .
198 .P
199 Otherwise,
200 .I pdfroff
201 usage closely mirrors that of
202 .I groff
203 itself.
204 .
205 Indeed,
206 with the exception of the
207 .BR \-h ,
208 .BR \-v ,
209 and
210 .BI \-T \ dev
211 short form options,
212 and all long form options,
213 which are parsed
214 internally by
215 .IR pdfroff ,
216 all options and file name arguments specified on the command line are
217 passed on to
218 .IR groff ,
219 to control the formatting of the PDF document.
220 .
221 Consequently,
222 .I pdfroff
223 accepts all options and arguments,
224 as specified in
225 .MR groff 1 ,
226 which may also be considered as the definitive reference for all
227 standard
228 .I pdfroff
229 options and argument usage.
230 .
231 .
232 .\" ====================================================================
233 .SH Options
234 .\" ====================================================================
235 .
236 .I pdfroff
237 accepts all of the short form options
238 (i.e.,
239 those introduced by a
240 single hyphen),
241 which are available with
242 .I groff
243 itself.
244 .
245 In most cases,
246 these are simply passed transparently to
247 .IR groff ;
248 the following,
249 however,
250 are handled specially by
251 .IR pdfroff .
252 .
253 .
254 .TP
255 .B \-h
256 Same as
257 .BR \-\-help ;
258 see below.
259 .
260 .
261 .TP
262 .B \-i
263 Process standard input,
264 after all other specified input files.
265 .
266 This is passed transparently to
267 .IR groff ,
268 but,
269 if grouped with other options,
270 it
271 .I must
272 be the first in the group.
273 .
274 Hiding it within a group breaks standard input processing,
275 in the multiple-pass
276 .I groff
277 processing context of
278 .IR pdfroff .
279 .
280 .
281 .TP
282 .BI \-T \ dev
283 Only
284 .B \-T\ ps
285 is supported by
286 .IR pdfroff .
287 .
288 Attempting to specify any other device causes
289 .I pdfroff
290 to abort.
291 .
292 .
293 .TP
294 .B \-v
295 Same as
296 .BR \-\-version ;
297 see below.
298 .
299 .
300 .P
301 See
302 .MR groff 1
303 for a description of all other short form options,
304 which are
305 transparently passed through
306 .I pdfroff
307 to
308 .IR groff .
309 .
310 .
311 .P
312 All long form options
313 (i.e.,
314 those introduced by a double hyphen)
315 are interpreted locally by
316 .IR pdfroff ;
317 they are
318 .I not
319 passed on to
320 .IR groff ,
321 unless otherwise stated below.
322 .
323 .
324 .TP
325 .B \-\-help
326 Causes
327 .I pdfroff
328 to display a summary of the its usage syntax,
329 and supported options,
330 and then exit.
331 .
332 .
333 .TP
334 .B \-\-emit\-ps
335 Suppresses the final output conversion step,
336 causing
337 .I pdfroff
338 to emit PostScript output instead of PDF.
339 .
340 This may be useful to capture intermediate PostScript output when using
341 a specialised postprocessor,
342 such as
343 .I gpresent
344 for example,
345 in place of the default Ghostscript PDF writer.
346 .
347 .
348 .TP
349 .B \-\-keep\-temporary\-files
350 Suppresses the deletion of temporary files,
351 which normally occurs
352 after
353 .I pdfroff
354 has completed PDF document formatting;
355 this may be useful when debugging formatting problems.
356 .
357 .
358 .IP
359 See section \[lq]Files\[rq] below for a description of the temporary
360 files used by
361 .IR pdfroff .
362 .
363 .
364 .TP
365 .B \-\-no\-pdf\-output
366 May be used with the
367 .BI \%\-\-reference\-dictionary= name
368 option
369 (described below)
370 to eliminate the overhead of PDF formatting when running
371 .I pdfroff
372 to create a reference dictionary for use in a different document.
373 .
374 .
375 .TP
376 .B \-\-no\-reference\-dictionary
377 May be used to eliminate the overhead of creating a reference
378 dictionary,
379 when it is known that the target PDF document contains no public
380 references,
381 created by the
382 .B pdfhref
383 macro.
384 .
385 .
386 .TP
387 .B \-\-no\-toc\-relocation
388 May be used to eliminate the extra
389 .I groff
390 processing pass,
391 which is required to generate a table of contents,
392 and relocate it to the start of the PDF document,
393 when processing any document which lacks an automatically
394 generated table of contents.
395 .
396 .
397 .TP
398 .B \-\-no\-kill\-null\-pages
399 While preparing for simulation of the manual collation step,
400 which is traditionally required to relocate a
401 .I "table of contents"
402 to the start of a document,
403 .I pdfroff
404 accumulates a number of empty page descriptions
405 into the intermediate PostScript output stream.
406 .
407 During the final collation step,
408 these empty pages are normally discarded from the finished document;
409 this option forces
410 .I pdfroff
411 to leave them in place.
412 .
413 .
414 .TP
415 .BI \-\-pdf\-output= name
416 Specifies the name to be used for the resultant PDF document;
417 if unspecified,
418 the PDF output is written to standard output.
419 .
420 A future version of
421 .I pdfroff
422 may use this option,
423 to encode the document name in a generated reference dictionary.
424 .
425 .
426 .TP
427 .BI \-\-reference\-dictionary= name
428 Specifies the name to be used for the generated reference dictionary
429 file;
430 if unspecified,
431 the reference dictionary is created in a temporary file,
432 which is deleted when
433 .I pdfroff
434 completes processing of the current document.
435 .
436 This option
437 .I must
438 be specified,
439 if it is desired to save the reference dictionary,
440 for use in references placed in other PDF documents.
441 .
442 .
443 .TP
444 .B \-\-report\-progress
445 Causes
446 .I pdfroff
447 to display an informational message on standard error,
448 at the start of each
449 .I groff
450 processing pass.
451 .
452 .
453 .TP
454 .BI \-\-stylesheet= name
455 Specifies the name of an
456 .IR "input file" ,
457 to be used as a style sheet for formatting of content,
458 which is to be placed
459 .I before
460 the table of contents,
461 in the formatted PDF document.
462 .
463 .
464 .TP
465 .B \-\-version
466 Causes
467 .I pdfroff
468 to display a version identification message.
469 .
470 The entire command line is then passed transparently to
471 .IR groff ,
472 in a
473 .I one
474 pass operation
475 .IR only ,
476 in order to display the associated
477 .I groff
478 version information,
479 before exiting.
480 .
481 .
482 .\" ====================================================================
483 .SH Environment
484 .\" ====================================================================
485 .
486 The following environment variables may be set,
487 and exported,
488 to modify the behaviour of
489 .IR pdfroff .
490 .
491 .
492 .TP
493 .I PDFROFF_COLLATE
494 Specifies the program to be used
495 for collation of the finished PDF document.
496 .
497 .
498 .IP
499 This collation step may be required to move
500 .I tables of contents
501 to the start of the finished PDF document,
502 when formatting with traditional macro packages,
503 which print them at the end.
504 .
505 However,
506 users should not normally need to specify
507 .IR \%PDFROFF_COLLATE ,
508 (and indeed,
509 are not encouraged to do so).
510 .
511 If unspecified,
512 .I pdfroff
513 uses
514 .MR sed 1
515 by default,
516 which normally suffices.
517 .
518 .
519 .IP
520 If
521 .I \%PDFROFF_COLLATE
522 .I is
523 specified,
524 then it must act as a filter,
525 accepting a list of file name arguments,
526 and write its output to the standard output stream,
527 whence it is piped to the
528 .IR \%PDFROFF_POSTPROCESSOR_COMMAND ,
529 to produce the finished PDF output.
530 .
531 .
532 .IP
533 When specifying
534 .IR \%PDFROFF_COLLATE ,
535 it is normally necessary to also specify
536 .IR \%PDFROFF_KILL_NULL_PAGES .
537 .
538 .
539 .IP
540 .I \%PDFROFF_COLLATE
541 is ignored,
542 if
543 .I pdfroff
544 is invoked with the
545 .B \%\-\-no\-kill\-null\-pages
546 option.
547 .
548 .
549 .TP
550 .I PDFROFF_KILL_NULL_PAGES
551 Specifies options to be passed to the
552 .I \%PDFROFF_COLLATE
553 program.
554 .
555 .
556 .IP
557 It should not normally be necessary to specify
558 .IR \%PDFROFF_KILL_NULL_PAGES .
559 .
560 The internal default is a
561 .MR sed 1
562 script,
563 which is intended to remove completely blank pages
564 from the collated output stream,
565 and which should be appropriate in most applications of
566 .IR pdfroff .
567 .
568 However,
569 if any alternative to
570 .MR sed 1
571 is specified for
572 .IR \%PDFROFF_COLLATE ,
573 then it is likely that a corresponding alternative specification for
574 .I \%PDFROFF_KILL_NULL_PAGES
575 is required.
576 .
577 .
578 .IP
579 As in the case of
580 .IR \%PDFROFF_COLLATE ,
581 .I \%PDFROFF_KILL_NULL_PAGES
582 is ignored,
583 if
584 .I pdfroff
585 is invoked with the
586 .B \%\-\-no\-kill\-null\-pages
587 option.
588 .
589 .
590 .TP
591 .I PDFROFF_POSTPROCESSOR_COMMAND
592 Specifies the command to be used for the final document conversion
593 from PostScript intermediate output to PDF.
594 .
595 It must behave as a filter,
596 writing its output to the standard output stream,
597 and must accept an arbitrary number of
598 .I files .\|.\|.\&
599 arguments,
600 with the special case of
601 .RB \[lq] \- \[rq]
602 representing the standard input stream.
603 .
604 .
605 .IP
606 If unspecified,
607 .I \%PDFROFF_POSTPROCESSOR_COMMAND
608 defaults to
609 .
610 .RS 12n
611 .EX
612 gs \-dBATCH \-dQUIET \-dNOPAUSE \-dSAFER \-sDEVICE=pdfwrite \e
613 \-sOutputFile=\-
614 .EE
615 .RE
616 .
617 .
618 .TP
619 .I GROFF_TMPDIR
620 Identifies the directory in which
621 .I pdfroff
622 should create a subdirectory for its temporary files.
623 .
624 If
625 .I \%GROFF_TMPDIR
626 is
627 .I not
628 specified,
629 then the variables
630 .IR TMPDIR ,
631 .I TMP
632 and
633 .I TEMP
634 are considered in turn as possible temporary file repositories.
635 .
636 If none of these are set,
637 then temporary files are created
638 in the current directory.
639 .
640 .
641 .TP
642 .I GROFF_GHOSTSCRIPT_INTERPRETER
643 Specifies the program to be invoked when
644 .I pdfroff
645 converts
646 .I groff
647 PostScript output to PDF.
648 .
649 If
650 .I \%PDFROFF_POSTPROCESSOR_COMMAND
651 is specified,
652 then the command name it specifies is
653 .I implicitly
654 assigned to
655 .IR \%GROFF_GHOSTSCRIPT_INTERPRETER ,
656 overriding any explicit setting specified in the environment.
657 .
658 If
659 .I \%GROFF_GHOSTSCRIPT_INTERPRETER
660 is not specified,
661 then
662 .I pdfroff
663 searches the process
664 .IR PATH ,
665 looking for a program with any of the well known names
666 for the Ghostscript interpreter;
667 if no Ghostscript interpreter can be found,
668 .I pdfroff
669 aborts.
670 .
671 .
672 .TP
673 .I GROFF_AWK_INTERPRETER
674 Specifies the program to be invoked when
675 .I pdfroff
676 is extracting reference dictionary entries from a
677 .I groff
678 intermediate message stream.
679 .
680 If
681 .I \%GROFF_AWK_INTERPRETER
682 is not specified,
683 then
684 .I pdfroff
685 searches the process
686 .IR PATH ,
687 looking for any of the preferred programs,
688 .IR gawk ,
689 .IR mawk ,
690 .IR nawk ,
691 and
692 .IR awk ,
693 in that order;
694 if none of these are found,
695 .I pdfroff
696 issues a warning message,
697 and continue processing;
698 however,
699 in this case,
700 no reference dictionary is created.
701 .
702 .
703 .TP
704 .I OSTYPE
705 Typically defined automatically by the operating system,
706 .I \%OSTYPE
707 is used on Microsoft Win32/MS-DOS platforms
708 .IR only ,
709 to infer the default
710 .I \%PATH_SEPARATOR
711 character,
712 which is used when parsing the process
713 .I PATH
714 to search for external helper programs.
715 .
716 .
717 .TP
718 .I PATH_SEPARATOR
719 If set,
720 .I \%PATH_SEPARATOR
721 overrides the default separator character,
722 (\[oq]:\[cq] on POSIX/Unix systems,
723 inferred from
724 .I \%OSTYPE
725 on Microsoft Win32/MS-DOS),
726 which is used when parsing the process
727 .I PATH
728 to search for external helper programs.
729 .
730 .
731 .TP
732 .I SHOW_PROGRESS
733 If this is set to a non-empty value,
734 then
735 .I pdfroff
736 always behaves as if the
737 .B \%\-\-report\-progress
738 option is specified on the command line.
739 .
740 .
741 .\" ====================================================================
742 .SH Files
743 .\" ====================================================================
744 .
745 Input and output files for
746 .I pdfroff
747 may be named according to any convention of the user's choice.
748 .
749 Typically,
750 input files may be named according to the choice of the principal
751 normatting macro package,
752 e.g.,
753 .RI file .ms
754 might be an input file for formatting using the
755 .I ms
756 macros
757 .RI ( s.tmac );
758 normally,
759 the final output file should be named
760 .RI file .pdf .
761 .
762 .
763 .P
764 Temporary files created by
765 .I pdfroff
766 are placed in the file system hierarchy,
767 in or below the directory specified by environment variables
768 (see section \[lq]Environment\[rq] above).
769 .
770 If
771 .MR mktemp 1
772 is available,
773 it is invoked to create a private subdirectory of
774 the nominated temporary files directory,
775 (with subdirectory name derived from the template
776 .IR pdfroff\-XXXXXXXXXX );
777 if this subdirectory is successfully created,
778 the temporary files will be placed within it,
779 otherwise they will be placed directly in the directory
780 nominated in the environment.
781 .
782 .
783 .P
784 All temporary files themselves
785 are named according to the convention
786 .IR pdf $$ . *,
787 where
788 .I $$
789 is the standard shell variable representing the process identifier of
790 the
791 .I pdfroff
792 process itself,
793 and
794 .I *
795 represents any of the extensions used by
796 .I pdfroff
797 to identify the following temporary and intermediate files.
798 .
799 .
800 .TP
801 .IR pdf $$ .tmp
802 A scratch pad file,
803 used to capture reference data emitted by
804 .IR groff ,
805 during the
806 .I reference dictionary
807 compilation phase.
808 .
809 .
810 .TP
811 .IR pdf $$ .ref
812 The
813 .IR "reference dictionary" ,
814 as compiled in the last but one pass of the
815 .I reference dictionary
816 compilation phase;
817 (at the start of the first pass,
818 this file is created empty;
819 in successive passes,
820 it contains the
821 .I reference dictionary
822 entries,
823 as collected in the preceding pass).
824 .
825 .
826 .IP
827 If the
828 .BR \%\-\-reference\-dictionary =\c
829 .I name
830 option is specified,
831 this intermediate file becomes permanent,
832 and is named
833 .IR name ,
834 rather than
835 .IR pdf $$ .ref .
836 .
837 .
838 .TP
839 .IR pdf $$ .cmp
840 Used to collect
841 .I reference dictionary
842 entries during the active pass of the
843 .I reference dictionary
844 compilation phase.
845 .
846 At the end of any pass,
847 when the content of
848 .IR pdf $$ .cmp
849 compares as identical to
850 .IR pdf $$ .ref ,
851 (or the corresponding file named by the
852 .BR \%\-\-reference\-dictionary =\c
853 .I name
854 option),
855 then
856 .I reference dictionary
857 compilation is terminated,
858 and the
859 .I document reference map
860 is appended to this intermediate file,
861 for inclusion in the final formatting passes.
862 .
863 .
864 .TP
865 .IR pdf $$ .tc
866 An intermediate
867 .I PostScript
868 file,
869 in which \[lq]Table of Contents\[rq] entries are collected,
870 to facilitate relocation before the body text,
871 on ultimate output to the
872 .I Ghostscript
873 postprocessor.
874 .
875 .
876 .TP
877 .IR pdf $$ .ps
878 An intermediate
879 .I PostScript
880 file,
881 in which the body text is collected prior to ultimate output to the
882 .I Ghostscript
883 postprocessor,
884 in the proper sequence,
885 .I after
886 .IR pdf $$ .tc .
887 .
888 .
889 .\" ====================================================================
890 .SH Authors
891 .\" ====================================================================
892 .
893 .I pdfroff
894 was written by
895 .MT keith\:.d\:.marshall@\:ntlworld\:.com
896 Keith Marshall
897 .ME ,
898 who maintains it at
899 .UR https://\:osdn\:.net/\:users/\:keith/\:pf/\:\%groff-pdfmark/\
900 \:wiki/\:\%FrontPage
901 his
902 .I groff-pdfmark
903 OSDN site
904 .UE .
905 .
906 .IR groff 's
907 version may be withdrawn in a future release.
908 .
909 .
910 .\" ====================================================================
911 .SH "See also"
912 .\" ====================================================================
913 .
914 .IR "Groff: The GNU Implementation of troff" ,
915 by Trent A.\& Fisher and Werner Lemberg,
916 is the primary
917 .I groff
918 manual.
919 .
920 You can browse it interactively with \[lq]info groff\[rq].
921 .
922 .
923 .P
924 Since
925 .I pdfroff
926 provides a superset of all
927 .I groff
928 capabilities,
929 the above manual,
930 or its terser reference page,
931 .MR groff 7
932 may also be considered definitive references to all
933 .I standard
934 capabilities of
935 .IR pdfroff ,
936 with this document providing the reference to
937 .IR pdfroff 's
938 extended features.
939 .
940 .
941 .P
942 While
943 .I pdfroff
944 imposes neither any restriction on,
945 nor any requirement for,
946 the use of any specific
947 .I groff
948 macro package,
949 a number of supplied macro packages,
950 and in particular those associated with the package
951 .IR \%pdfmark.tmac ,
952 are best suited for use with
953 .I pdfroff
954 as the preferred formatter.
955 .
956 .
957 .TP
958 .I /usr/\:\%share/\:\%doc/\:\%packages/\:\%groff/\:\%pdf/\:\%pdfmark.pdf
959 \[lq]Portable Document Format Publishing with GNU
960 .IR Troff \[rq],
961 by Keith Marshall,
962 offers detailed documentation on the use of these packages.
963 .
964 This file,
965 together with its source,
966 .IR \%pdfmark.ms ,
967 is part of the
968 .I groff
969 distribution.
970 .
971 .
972 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
973 .cp \n[*groff_pdfroff_1_man_C]
974 .do rr *groff_pdfroff_1_man_C
975 .
976 .
977 .\" Local Variables:
978 .\" fill-column: 72
979 .\" mode: nroff
980 .\" End:
981 .\" vim: set filetype=groff textwidth=72: