Debian Codegraph @

upstream/mageia-cauldron/man1/pdfroff.1

raw
1 .TH pdfroff 1 "13 July 2025" "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 a subdirectory of
639 .BR /tmp .
640 .
641 .
642 .TP
643 .I GROFF_GHOSTSCRIPT_INTERPRETER
644 Specifies the program to be invoked when
645 .I pdfroff
646 converts
647 .I groff
648 PostScript output to PDF.
649 .
650 If
651 .I \%PDFROFF_POSTPROCESSOR_COMMAND
652 is specified,
653 then the command name it specifies is
654 .I implicitly
655 assigned to
656 .IR \%GROFF_GHOSTSCRIPT_INTERPRETER ,
657 overriding any explicit setting specified in the environment.
658 .
659 If
660 .I \%GROFF_GHOSTSCRIPT_INTERPRETER
661 is not specified,
662 then
663 .I pdfroff
664 searches the process
665 .IR PATH ,
666 looking for a program with any of the well known names
667 for the Ghostscript interpreter;
668 if no Ghostscript interpreter can be found,
669 .I pdfroff
670 aborts.
671 .
672 .
673 .TP
674 .I GROFF_AWK_INTERPRETER
675 Specifies the program to be invoked when
676 .I pdfroff
677 is extracting reference dictionary entries from a
678 .I groff
679 intermediate message stream.
680 .
681 If
682 .I \%GROFF_AWK_INTERPRETER
683 is not specified,
684 then
685 .I pdfroff
686 searches the process
687 .IR PATH ,
688 looking for any of the preferred programs,
689 .IR gawk ,
690 .IR mawk ,
691 .IR nawk ,
692 and
693 .IR awk ,
694 in that order;
695 if none of these are found,
696 .I pdfroff
697 issues a warning message,
698 and continue processing;
699 however,
700 in this case,
701 no reference dictionary is created.
702 .
703 .
704 .TP
705 .I OSTYPE
706 Typically defined automatically by the operating system,
707 .I \%OSTYPE
708 is used on Microsoft Win32/MS-DOS platforms
709 .IR only ,
710 to infer the default
711 .I \%PATH_SEPARATOR
712 character,
713 which is used when parsing the process
714 .I PATH
715 to search for external helper programs.
716 .
717 .
718 .TP
719 .I PATH_SEPARATOR
720 If set,
721 .I \%PATH_SEPARATOR
722 overrides the default separator character,
723 (\[oq]:\[cq] on POSIX/Unix systems,
724 inferred from
725 .I \%OSTYPE
726 on Microsoft Win32/MS-DOS),
727 which is used when parsing the process
728 .I PATH
729 to search for external helper programs.
730 .
731 .
732 .TP
733 .I SHOW_PROGRESS
734 If this is set to a non-empty value,
735 then
736 .I pdfroff
737 always behaves as if the
738 .B \%\-\-report\-progress
739 option is specified on the command line.
740 .
741 .
742 .\" ====================================================================
743 .SH Files
744 .\" ====================================================================
745 .
746 Input and output files for
747 .I pdfroff
748 may be named according to any convention of the user's choice.
749 .
750 Typically,
751 input files may be named according to the choice of the principal
752 normatting macro package,
753 e.g.,
754 .RI file .ms
755 might be an input file for formatting using the
756 .I ms
757 macros
758 .RI ( s.tmac );
759 normally,
760 the final output file should be named
761 .RI file .pdf .
762 .
763 .
764 .P
765 Temporary files created by
766 .I pdfroff
767 are placed in the file system hierarchy,
768 in or below the directory specified by environment variables
769 (see section \[lq]Environment\[rq] above).
770 .
771 If
772 .MR mktemp 1
773 is available,
774 it is invoked to create a private subdirectory of
775 the nominated temporary files directory,
776 (with subdirectory name derived from the template
777 .IR pdfroff\-XXXXXXXXXX );
778 if this subdirectory is successfully created,
779 the temporary files will be placed within it,
780 otherwise they will be placed directly in the directory
781 nominated in the environment.
782 .
783 .
784 .P
785 All temporary files themselves
786 are named according to the convention
787 .IR pdf $$ . *,
788 where
789 .I $$
790 is the standard shell variable representing the process identifier of
791 the
792 .I pdfroff
793 process itself,
794 and
795 .I *
796 represents any of the extensions used by
797 .I pdfroff
798 to identify the following temporary and intermediate files.
799 .
800 .
801 .TP
802 .IR pdf $$ .tmp
803 A scratch pad file,
804 used to capture reference data emitted by
805 .IR groff ,
806 during the
807 .I reference dictionary
808 compilation phase.
809 .
810 .
811 .TP
812 .IR pdf $$ .ref
813 The
814 .IR "reference dictionary" ,
815 as compiled in the last but one pass of the
816 .I reference dictionary
817 compilation phase;
818 (at the start of the first pass,
819 this file is created empty;
820 in successive passes,
821 it contains the
822 .I reference dictionary
823 entries,
824 as collected in the preceding pass).
825 .
826 .
827 .IP
828 If the
829 .BR \%\-\-reference\-dictionary =\c
830 .I name
831 option is specified,
832 this intermediate file becomes permanent,
833 and is named
834 .IR name ,
835 rather than
836 .IR pdf $$ .ref .
837 .
838 .
839 .TP
840 .IR pdf $$ .cmp
841 Used to collect
842 .I reference dictionary
843 entries during the active pass of the
844 .I reference dictionary
845 compilation phase.
846 .
847 At the end of any pass,
848 when the content of
849 .IR pdf $$ .cmp
850 compares as identical to
851 .IR pdf $$ .ref ,
852 (or the corresponding file named by the
853 .BR \%\-\-reference\-dictionary =\c
854 .I name
855 option),
856 then
857 .I reference dictionary
858 compilation is terminated,
859 and the
860 .I document reference map
861 is appended to this intermediate file,
862 for inclusion in the final formatting passes.
863 .
864 .
865 .TP
866 .IR pdf $$ .tc
867 An intermediate
868 .I PostScript
869 file,
870 in which \[lq]Table of Contents\[rq] entries are collected,
871 to facilitate relocation before the body text,
872 on ultimate output to the
873 .I Ghostscript
874 postprocessor.
875 .
876 .
877 .TP
878 .IR pdf $$ .ps
879 An intermediate
880 .I PostScript
881 file,
882 in which the body text is collected prior to ultimate output to the
883 .I Ghostscript
884 postprocessor,
885 in the proper sequence,
886 .I after
887 .IR pdf $$ .tc .
888 .
889 .
890 .\" ====================================================================
891 .SH Authors
892 .\" ====================================================================
893 .
894 .I pdfroff
895 was written by
896 .MT keith\:.d\:.marshall@\:ntlworld\:.com
897 Keith Marshall
898 .ME ,
899 who maintains it at
900 .UR https://\:osdn\:.net/\:users/\:keith/\:pf/\:\%groff-pdfmark/\
901 \:wiki/\:\%FrontPage
902 his
903 .I groff-pdfmark
904 OSDN site
905 .UE .
906 .
907 .IR groff 's
908 version may be withdrawn in a future release.
909 .
910 .
911 .\" ====================================================================
912 .SH "See also"
913 .\" ====================================================================
914 .
915 .IR "Groff: The GNU Implementation of troff" ,
916 by Trent A.\& Fisher and Werner Lemberg,
917 is the primary
918 .I groff
919 manual.
920 .
921 You can browse it interactively with \[lq]info groff\[rq].
922 .
923 .
924 .P
925 Since
926 .I pdfroff
927 provides a superset of all
928 .I groff
929 capabilities,
930 the above manual,
931 or its terser reference page,
932 .MR groff 7
933 may also be considered definitive references to all
934 .I standard
935 capabilities of
936 .IR pdfroff ,
937 with this document providing the reference to
938 .IR pdfroff 's
939 extended features.
940 .
941 .
942 .P
943 While
944 .I pdfroff
945 imposes neither any restriction on,
946 nor any requirement for,
947 the use of any specific
948 .I groff
949 macro package,
950 a number of supplied macro packages,
951 and in particular those associated with the package
952 .IR \%pdfmark.tmac ,
953 are best suited for use with
954 .I pdfroff
955 as the preferred formatter.
956 .
957 .
958 .TP
959 .I /usr/\:\%share/\:\%doc/\:\%groff/\:\%pdf/\:\%pdfmark.pdf
960 \[lq]Portable Document Format Publishing with GNU
961 .IR Troff \[rq],
962 by Keith Marshall,
963 offers detailed documentation on the use of these packages.
964 .
965 This file,
966 together with its source,
967 .IR \%pdfmark.ms ,
968 is part of the
969 .I groff
970 distribution.
971 .
972 .
973 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
974 .cp \n[*groff_pdfroff_1_man_C]
975 .do rr *groff_pdfroff_1_man_C
976 .
977 .
978 .\" Local Variables:
979 .\" fill-column: 72
980 .\" mode: nroff
981 .\" End:
982 .\" vim: set filetype=groff textwidth=72: