1 .TH PDFROFF @MAN1EXT@ "@MDATE@" "groff @VERSION@"
3 pdfroff \- create PDF documents using groff
6 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
7 .do nr pdfroff_C \n[.C]
12 .\" File position: <groff-source>/contrib/pdfmark/pdfroff.man
14 .\" ====================================================================
16 .\" ====================================================================
18 .\" Copyright (C) 2005-2018 Free Software Foundation, Inc.
20 .\" This file is part of groff, the GNU roff type-setting system.
22 .\" Permission is granted to copy, distribute and/or modify this
23 .\" document under the terms of the GNU Free Documentation License,
24 .\" Version 1.3 or any later version published by the Free Software
25 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
26 .\" and with no Back-Cover Texts.
28 .\" A copy of the Free Documentation License is included as a file
29 .\" called FDL in the main directory of the groff source package.
32 .\" ====================================================================
33 .\" Local macro definitions
38 .\" ====================================================================
42 .\" ====================================================================
44 .\" ====================================================================
47 .OP \-abcegilpstzCEGNRSUVXZ
63 .OP \-\-no\-toc\-relocation
64 .OP \-\-no-kill\-null\-pages
65 .RB [ \-\-stylesheet=\c
67 .OP \-\-no\-pdf\-output
68 .RB [ \-\-pdf\-output=\c
70 .OP \-\-no\-reference\-dictionary
71 .RB [ \-\-reference\-dictionary=\c
73 .OP \-\-report\-progress
74 .OP \-\-keep\-temporary\-files
96 .\" ====================================================================
98 .\" ====================================================================
101 is a wrapper program for the GNU text processing system,
104 It transparently handles the mechanics of multiple pass
106 processing, when applied to suitably marked up
109 such that tables of contents and body text are formatted separately,
110 and are subsequently combined in the correct order, for final publication
111 as a single PDF document.
114 \*(lqstyle sheet\*(rq
115 capability is provided;
116 this allows for the definition of content which is required to precede the
117 table of contents, in the published document.
120 For each invocation of
124 output stream is post-processed by the GhostScript interpreter,
125 to produce a finished PDF document.
129 makes no assumptions about, and imposes no restrictions on, the use of
132 macro packages which the user may choose to employ,
133 in order to achieve a desired document format;
136 include specific built in support for the
138 macro package, should the user choose to employ it.
142 macro, defined in the
144 package, is used to define public reference marks, or dynamic links to
145 such reference marks, then
147 performs as many preformatting
149 passes as required, up to a maximum limit of
151 in order to compile a document reference dictionary, to resolve
152 references, and to expand the dynamically defined content of links.
155 .\" ====================================================================
157 .\" ====================================================================
159 The command line is parsed in accordance with normal GNU conventions,
160 but with one exception \(em when specifying any short form option
161 (i.e., a single character option introduced by a single hyphen),
162 and if that option expects an argument, then it
164 be specified independently (i.e., it may
166 be appended to any group of other single character short form options).
170 Long form option names (i.e., those introduced by a double hyphen) may
171 be abbreviated to their minimum length unambiguous initial substring.
177 usage closely mirrors that of
181 Indeed, with the exception of the
186 short form options, and all long form options, which are parsed
189 all options and file name arguments specified on the command line are
192 to control the formatting of the PDF document.
196 accepts all options and arguments, as specified in
197 .BR groff (@MAN1EXT@),
198 which may also be considered as the definitive reference for all standard
200 options and argument usage.
203 .\" ====================================================================
205 .\" ====================================================================
208 accepts all of the short form options (i.e., those introduced by a
209 single hyphen), which are available with
213 In most cases, these are simply passed transparently to
215 the following, however, are handled specially by
226 Process standard input, after all other specified input files.
228 This is passed transparently to
230 but, if grouped with other options, it
232 be the first in the group.
234 Hiding it within a group breaks standard input processing, in the
237 processing context of
247 Attempting to specify any other device causes
260 .BR groff (@MAN1EXT@)
261 for a description of all other short form options, which are
262 transparently passed through
269 All long form options (i.e., those introduced by a double hyphen) are
270 interpreted locally by
276 unless otherwise stated below.
282 to display a summary of the its usage syntax, and supported options,
287 Suppresses the final output conversion step, causing
289 to emit PostScript output instead of PDF.
291 This may be useful, to capture intermediate PostScript output, when
292 using a specialised postprocessor, such as
295 in place of the default
300 .B \-\-keep\-temporary\-files
301 Suppresses the deletion of temporary files, which normally occurs
304 has completed PDF document formatting; this may be useful, when
305 debugging formatting problems.
308 See section \[lq]Files\[rq] below for a description of the temporary
313 .B \-\-no\-pdf\-output
315 .BI \%\-\-reference\-dictionary= name
316 option (described below) to eliminate the overhead of PDF formatting,
319 to create a reference dictionary, for use in a different document.
322 .B \-\-no\-reference\-dictionary
323 May be used to eliminate the overhead of creating a reference dictionary,
324 when it is known that the target PDF document contains no public
325 references, created by the
330 .B \-\-no\-toc\-relocation
331 May be used to eliminate the extra
334 which is required to generate a table of contents,
335 and relocate it to the start of the PDF document,
336 when processing any document which lacks an automatically
337 generated table of contents.
340 .B \-\-no\-kill\-null\-pages
341 While preparing for simulation of the manual collation step,
342 which is traditionally required to relocate a
343 .I "table of contents"
344 to the start of a document,
346 accumulates a number of empty page descriptions
347 into the intermediate
350 During the final collation step,
351 these empty pages are normally discarded from the finished document;
354 to leave them in place.
357 .BI \-\-pdf\-output= name
358 Specifies the name to be used for the resultant PDF document;
359 if unspecified, the PDF output is written to standard output.
363 to encode the document name in a generated reference dictionary.
366 .BI \-\-reference\-dictionary= name
367 Specifies the name to be used for the generated reference dictionary file;
368 if unspecified, the reference dictionary is created in a temporary file,
369 which is deleted when
371 completes processing of the current document.
375 be specified, if it is desired to save the reference dictionary,
376 for use in references placed in other PDF documents.
379 .B \-\-report\-progress
382 to display an informational message on standard error,
388 .BI \-\-stylesheet= name
389 Specifies the name of an
391 to be used as a style sheet for formatting of content,
392 which is to be placed
394 the table of contents,
395 in the formatted PDF document.
401 to display a version identification message.
403 The entire command line is then passed transparently to
409 in order to display the associated
411 version information, before exiting.
414 .\" ====================================================================
416 .\" ====================================================================
418 The following environment variables may be set, and exported,
419 to modify the behaviour of
424 Specifies the program to be used
425 for collation of the finished PDF document.
428 This collation step may be required to move
429 .I tables of contents
430 to the start of the finished PDF document,
431 when formatting with traditional macro packages,
432 which print them at the end.
434 However, users should not normally need to specify
435 .IR \%PDFROFF_COLLATE ,
436 (and indeed, are not encouraged to do so). If unspecified,
441 which normally suffices.
448 then it must act as a filter,
449 accepting a list of file name arguments,
450 and write its output to the
453 whence it is piped to the
454 .IR \%PDFROFF_POSTPROCESSOR_COMMAND ,
455 to produce the finished PDF output.
459 .IR \%PDFROFF_COLLATE ,
460 it is normally necessary to also specify
461 .IR \%PDFROFF_KILL_NULL_PAGES .
469 .I \%\-\-no\-kill\-null\-pages
473 .I PDFROFF_KILL_NULL_PAGES
474 Specifies options to be passed to the
479 It should not normally be necessary to specify
480 .IR \%PDFROFF_KILL_NULL_PAGES .
482 The internal default is a
485 which is intended to remove completely blank pages
486 from the collated output stream,
487 and which should be appropriate in most applications of
491 if any alternative to
494 .IR \%PDFROFF_COLLATE ,
495 then it is likely that a corresponding alternative specification for
496 .I \%PDFROFF_KILL_NULL_PAGES
501 .IR \%PDFROFF_COLLATE ,
502 .I \%PDFROFF_KILL_NULL_PAGES
506 .I \%\-\-no\-kill\-null\-pages
510 .I PDFROFF_POSTPROCESSOR_COMMAND
511 Specifies the command to be used for the final document conversion
512 from PostScript intermediate output to PDF.
514 It must behave as a filter,
515 writing its output to the
518 and must accept an arbitrary number of
521 with the special case of
529 .I \%PDFROFF_POSTPROCESSOR_COMMAND
534 gs \-dBATCH \-dQUIET \-dNOPAUSE \-dSAFER \-sDEVICE=pdfwrite \e
541 Identifies the directory in which
543 should create temporary files.
549 specified, then the variables
554 are considered in turn, as possible temporary file repositories.
555 If none of these are set, then temporary files are created
556 in the current directory.
559 .I GROFF_GHOSTSCRIPT_INTERPRETER
560 Specifies the program to be invoked, when
564 PostScript output to PDF.
567 .I \%PDFROFF_POSTPROCESSOR_COMMAND
569 then the command name it specifies is
572 .IR \%GROFF_GHOSTSCRIPT_INTERPRETER ,
573 overriding any explicit setting specified in the environment.
576 .I \%GROFF_GHOSTSCRIPT_INTERPRETER
577 is not specified, then
581 looking for a program with any of the well known names
582 for the GhostScript interpreter;
583 if no GhostScript interpreter can be found,
588 .I GROFF_AWK_INTERPRETER
589 Specifies the program to be invoked, when
591 is extracting reference dictionary entries from a
593 intermediate message stream.
596 .I \%GROFF_AWK_INTERPRETER
597 is not specified, then
601 looking for any of the preferred programs, \[oq]gawk\[cq],
602 \[oq]mawk\[cq], \[oq]nawk\[cq], and \[oq]awk\[cq], in this order; if
603 none of these are found,
605 issues a warning message, and continue processing;
606 however, in this case, no reference dictionary is created.
610 Typically defined automatically by the operating system,
612 is used on Microsoft Win32/MS-DOS platforms
617 which is used when parsing the process
619 to search for external helper programs.
625 overrides the default separator character,
626 (\[oq]:\[cq] on POSIX/Unix systems,
629 on Microsoft Win32/MS-DOS),
630 which is used when parsing the process
632 to search for external helper programs.
636 If this is set to a non-empty value, then
638 always behaves as if the
639 .B \%\-\-report\-progress
640 option is specified, on the command line.
643 .\" ====================================================================
645 .\" ====================================================================
647 Input and output files for
649 may be named according to any convention of the user's choice.
650 Typically, input files may be named according to the choice of the
651 principal formatting macro package, e.g.,
653 might be an input file for formatting using the
657 normally, the final output file should be named
662 Temporary files, created by
664 are placed in the file system hierarchy,
665 in or below the directory specified by environment variables
666 (see section \[lq]Environment\[rq] above).
669 .BR mktemp (@MAN1EXT@)
671 it is invoked to create a private subdirectory of
672 the nominated temporary files directory,
673 (with subdirectory name derived from the template
674 .IR pdfroff\-XXXXXXXXXX );
675 if this subdirectory is successfully created,
676 the temporary files will be placed within it,
677 otherwise they will be placed directly in the directory
678 nominated in the environment.
680 All temporary files themselves
681 are named according to the convention
685 is the standard shell variable representing the process ID of the
689 represents any of the extensions used by
691 to identify the following temporary and intermediate files.
696 used to capture reference data emitted by
699 .I reference dictionary
705 .IR "reference dictionary" ,
706 as compiled in the last but one pass of the
707 .I reference dictionary
709 (at the start of the first pass,
710 this file is created empty;
711 in successive passes,
713 .I reference dictionary
715 as collected in the preceding pass).
719 .BR \%\-\-reference\-dictionary =\c
722 this intermediate file becomes permanent,
731 .I reference dictionary
732 entries during the active pass of the
733 .I reference dictionary
736 At the end of any pass,
739 compares as identical to
741 (or the corresponding file named by the
742 .BR \%\-\-reference\-dictionary =\c
746 .I reference dictionary
747 compilation is terminated,
749 .I document reference map
750 is appended to this intermediate file,
751 for inclusion in the final formatting passes.
758 in which \[lq]Table of Contents\[rq] entries are collected,
759 to facilitate relocation before the body text,
760 on ultimate output to the
769 in which the body text is collected prior to ultimate output to the
772 in the proper sequence,
777 .\" ====================================================================
779 .\" ====================================================================
782 .MT keith.d.marshall@\:ntlworld.com
787 .\" ====================================================================
789 .\" ====================================================================
792 .BR groff (@MAN1EXT@)
793 for the definitive reference to document formatting with
798 provides a superset of all
801 .BR groff (@MAN1EXT@)
802 may also be considered to be the definitive reference to all
806 with this document providing the reference to
814 imposes neither any restriction on, nor any requirement for,
815 the use of any specific
817 macro package, a number of supplied macro packages,
818 and in particular those associated with the package
820 are best suited for use with
822 as the preferred formatter.
824 Detailed documentation on the use of these packages may be found,
825 in PDF format, in the reference guide
826 .BR "\*(lqPortable Document Format Publishing with GNU Troff\*(rq" ,
827 included in the installed documentation set as
828 .IR @PDFDOCDIR@/pdfmark.pdf .
831 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
835 .\" ====================================================================
839 .\" vim: filetype=groff: