{ "mode": "man", "parameter": "pdfroff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pdfroff/1/json", "generated": "2026-10-22T00:50:54Z", "sections": { "Name": { "content": "pdfroff - construct files in Portable Document Format using groff\n", "subsections": [] }, "Synopsis": { "content": "pdfroff [groff-option] [--emit-ps] [--no-toc-relocation] [--no-kill-null-pages]\n[--stylesheet=name] [--no-pdf-output] [--pdf-output=name] [--no-reference-dictionary]\n[--reference-dictionary=name] [--report-progress] [--keep-temporary-files] [file ...]\n", "subsections": [ { "name": "pdfroff -h", "content": "" }, { "name": "pdfroff --help", "content": "pdfroff -v [groff-option ...]\npdfroff --version [groff-option ...]\n\ngroff-option is any short option supported by groff(1) except for -h, -T, and -v; see section\n“Usage” below.\n" } ] }, "Description": { "content": "pdfroff is a wrapper program for the GNU text processing system, groff. It transparently\nhandles the mechanics of multiple pass groff processing, when applied to suitably marked up\ngroff source files, such that tables of contents and body text are formatted separately, and\nare subsequently combined in the correct order, for final publication as a single PDF docu‐\nment. A further optional “style sheet” capability is provided; this allows for the defini‐\ntion of content which is required to precede the table of contents, in the published docu‐\nment.\n\nFor each invocation of pdfroff, the ultimate groff output stream is post-processed by the\nGhostscript gs(1) interpreter to produce a finished PDF document.\n\npdfroff makes no assumptions about, and imposes no restrictions on, the use of any groff\nmacro packages which the user may choose to employ, in order to achieve a desired document\nformat; however, it does include specific built in support for the pdfmark macro package,\nshould the user choose to employ it. Specifically, if the pdfhref macro, defined in the\npdfmark.tmac package, is used to define public reference marks, or dynamic links to such ref‐\nerence marks, then pdfroff performs as many preformatting groff passes as required, up to a\nmaximum limit of four, in order to compile a document reference dictionary, to resolve refer‐\nences, and to expand the dynamically defined content of links.\n", "subsections": [] }, "Usage": { "content": "The command line is parsed in accordance with normal GNU conventions, but with one exception—\nwhen specifying any short form option (i.e., a single character option introduced by a single\nhyphen), and if that option expects an argument, then it must be specified independently\n(i.e., it may not be appended to any group of other single character short form options).\n\nLong form option names (i.e., those introduced by a double hyphen) may be abbreviated to\ntheir minimum length unambiguous initial substring.\n\nOtherwise, pdfroff usage closely mirrors that of groff itself. Indeed, with the exception of\nthe -h, -v, and -T dev short form options, and all long form options, which are parsed inter‐\nnally by pdfroff, all options and file name arguments specified on the command line are\npassed on to groff, to control the formatting of the PDF document. Consequently, pdfroff ac‐\ncepts all options and arguments, as specified in groff(1), which may also be considered as\nthe definitive reference for all standard pdfroff options and argument usage.\n", "subsections": [] }, "Options": { "content": "pdfroff accepts all of the short form options (i.e., those introduced by a single hyphen),\nwhich are available with groff itself. In most cases, these are simply passed transparently\nto groff; the following, however, are handled specially by pdfroff.\n", "subsections": [ { "name": "-h --help", "content": "", "flag": "-h", "long": "--help" }, { "name": "-i", "content": "parently to groff, but, if grouped with other options, it must be the first in the\ngroup. Hiding it within a group breaks standard input processing, in the multiple-\npass groff processing context of pdfroff.\n", "flag": "-i" }, { "name": "-T _ -T ps", "content": "pdfroff to abort.\n", "flag": "-T" }, { "name": "-v --version", "content": "See groff(1) for a description of all other short form options, which are transparently\npassed through pdfroff to groff.\n\nAll long form options (i.e., those introduced by a double hyphen) are interpreted locally by\npdfroff; they are not passed on to groff, unless otherwise stated below.\n\n--help Causes pdfroff to display a summary of the its usage syntax, and supported options,\nand then exit.\n", "flag": "-v", "long": "--version" }, { "name": "--emit-ps", "content": "Suppresses the final output conversion step, causing pdfroff to emit PostScript output\ninstead of PDF. This may be useful to capture intermediate PostScript output when us‐\ning a specialised postprocessor, such as gpresent for example, in place of the default\nGhostscript PDF writer.\n", "long": "--emit-ps" }, { "name": "--keep-temporary-files", "content": "Suppresses the deletion of temporary files, which normally occurs after pdfroff has\ncompleted PDF document formatting; this may be useful when debugging formatting prob‐\nlems.\n\nSee section “Files” below for a description of the temporary files used by pdfroff.\n", "long": "--keep-temporary-files" }, { "name": "--no-pdf-output", "content": "May be used with the --reference-dictionary=name option (described below) to eliminate\nthe overhead of PDF formatting when running pdfroff to create a reference dictionary\nfor use in a different document.\n", "long": "--no-pdf-output" }, { "name": "--no-reference-dictionary", "content": "May be used to eliminate the overhead of creating a reference dictionary, when it is\nknown that the target PDF document contains no public references, created by the\npdfhref macro.\n", "long": "--no-reference-dictionary" }, { "name": "--no-toc-relocation", "content": "May be used to eliminate the extra groff processing pass, which is required to gener‐\nate a table of contents, and relocate it to the start of the PDF document, when pro‐\ncessing any document which lacks an automatically generated table of contents.\n", "long": "--no-toc-relocation" }, { "name": "--no-kill-null-pages", "content": "While preparing for simulation of the manual collation step, which is traditionally\nrequired to relocate a table of contents to the start of a document, pdfroff accumu‐\nlates a number of empty page descriptions into the intermediate PostScript output\nstream. During the final collation step, these empty pages are normally discarded\nfrom the finished document; this option forces pdfroff to leave them in place.\n\n--pdf-output=name\nSpecifies the name to be used for the resultant PDF document; if unspecified, the PDF\noutput is written to standard output. A future version of pdfroff may use this op‐\ntion, to encode the document name in a generated reference dictionary.\n\n--reference-dictionary=name\nSpecifies the name to be used for the generated reference dictionary file; if unspeci‐\nfied, the reference dictionary is created in a temporary file, which is deleted when\npdfroff completes processing of the current document. This option must be specified,\nif it is desired to save the reference dictionary, for use in references placed in\nother PDF documents.\n", "long": "--no-kill-null-pages" }, { "name": "--report-progress", "content": "Causes pdfroff to display an informational message on standard error, at the start of\neach groff processing pass.\n\n--stylesheet=name\nSpecifies the name of an input file, to be used as a style sheet for formatting of\ncontent, which is to be placed before the table of contents, in the formatted PDF doc‐\nument.\n", "long": "--report-progress" }, { "name": "--version", "content": "Causes pdfroff to display a version identification message. The entire command line\nis then passed transparently to groff, in a one pass operation only, in order to dis‐\nplay the associated groff version information, before exiting.\n", "long": "--version" } ] }, "Environment": { "content": "The following environment variables may be set, and exported, to modify the behaviour of\npdfroff.\n\nPDFROFFCOLLATE\nSpecifies the program to be used for collation of the finished PDF document.\n\nThis collation step may be required to move tables of contents to the start of the\nfinished PDF document, when formatting with traditional macro packages, which print\nthem at the end. However, users should not normally need to specify PDFROFFCOLLATE,\n(and indeed, are not encouraged to do so). If unspecified, pdfroff uses sed(1) by de‐\nfault, which normally suffices.\n\nIf PDFROFFCOLLATE is specified, then it must act as a filter, accepting a list of\nfile name arguments, and write its output to the standard output stream, whence it is\npiped to the PDFROFFPOSTPROCESSORCOMMAND, to produce the finished PDF output.\n\nWhen specifying PDFROFFCOLLATE, it is normally necessary to also specify\nPDFROFFKILLNULLPAGES.\n\nPDFROFFCOLLATE is ignored, if pdfroff is invoked with the --no-kill-null-pages op‐\ntion.\n\nPDFROFFKILLNULLPAGES\nSpecifies options to be passed to the PDFROFFCOLLATE program.\n\nIt should not normally be necessary to specify PDFROFFKILLNULLPAGES. The internal\ndefault is a sed(1) script, which is intended to remove completely blank pages from\nthe collated output stream, and which should be appropriate in most applications of\npdfroff. However, if any alternative to sed(1) is specified for PDFROFFCOLLATE, then\nit is likely that a corresponding alternative specification for\nPDFROFFKILLNULLPAGES is required.\n\nAs in the case of PDFROFFCOLLATE, PDFROFFKILLNULLPAGES is ignored, if pdfroff is\ninvoked with the --no-kill-null-pages option.\n\nPDFROFFPOSTPROCESSORCOMMAND\nSpecifies the command to be used for the final document conversion from PostScript in‐\ntermediate output to PDF. It must behave as a filter, writing its output to the stan‐\ndard output stream, and must accept an arbitrary number of files ... arguments, with\nthe special case of “-” representing the standard input stream.\n\nIf unspecified, PDFROFFPOSTPROCESSORCOMMAND defaults to\ngs -dBATCH -dQUIET -dNOPAUSE -dSAFER -sDEVICE=pdfwrite \\\n-sOutputFile=-\n\nGROFFTMPDIR\nIdentifies the directory in which pdfroff should create temporary files. If\nGROFFTMPDIR is not specified, then the variables TMPDIR, TMP and TEMP are considered\nin turn as possible temporary file repositories. If none of these are set, then tem‐\nporary files are created in the current directory.\n\nGROFFGHOSTSCRIPTINTERPRETER\nSpecifies the program to be invoked when pdfroff converts groff PostScript output to\nPDF. If PDFROFFPOSTPROCESSORCOMMAND is specified, then the command name it speci‐\nfies is implicitly assigned to GROFFGHOSTSCRIPTINTERPRETER, overriding any explicit\nsetting specified in the environment. If GROFFGHOSTSCRIPTINTERPRETER is not speci‐\nfied, then pdfroff searches the process PATH, looking for a program with any of the\nwell known names for the Ghostscript interpreter; if no Ghostscript interpreter can be\nfound, pdfroff aborts.\n\nGROFFAWKINTERPRETER\nSpecifies the program to be invoked when pdfroff is extracting reference dictionary\nentries from a groff intermediate message stream. If GROFFAWKINTERPRETER is not\nspecified, then pdfroff searches the process PATH, looking for any of the preferred\nprograms, gawk, mawk, nawk, and awk, in that order; if none of these are found,\npdfroff issues a warning message, and continue processing; however, in this case, no\nreference dictionary is created.\n\nOSTYPE Typically defined automatically by the operating system, OSTYPE is used on Microsoft\nWin32/MS-DOS platforms only, to infer the default PATHSEPARATOR character, which is\nused when parsing the process PATH to search for external helper programs.\n\nPATHSEPARATOR\nIf set, PATHSEPARATOR overrides the default separator character, (‘:’ on POSIX/Unix\nsystems, inferred from OSTYPE on Microsoft Win32/MS-DOS), which is used when parsing\nthe process PATH to search for external helper programs.\n\nSHOWPROGRESS\nIf this is set to a non-empty value, then pdfroff always behaves as if the\n--report-progress option is specified on the command line.\n", "subsections": [] }, "Files": { "content": "Input and output files for pdfroff may be named according to any convention of the user's\nchoice. Typically, input files may be named according to the choice of the principal normat‐\nting macro package, e.g., file.ms might be an input file for formatting using the ms macros\n(s.tmac); normally, the final output file should be named file.pdf.\n\nTemporary files created by pdfroff are placed in the file system hierarchy, in or below the\ndirectory specified by environment variables (see section “Environment” above). If mktemp(1)\nis available, it is invoked to create a private subdirectory of the nominated temporary files\ndirectory, (with subdirectory name derived from the template pdfroff-XXXXXXXXXX); if this\nsubdirectory is successfully created, the temporary files will be placed within it, otherwise\nthey will be placed directly in the directory nominated in the environment.\n\nAll temporary files themselves are named according to the convention pdf$$.*, where $$ is the\nstandard shell variable representing the process identifier of the pdfroff process itself,\nand * represents any of the extensions used by pdfroff to identify the following temporary\nand intermediate files.\n\npdf$$.tmp\nA scratch pad file, used to capture reference data emitted by groff, during the refer‐\nence dictionary compilation phase.\n\npdf$$.ref\nThe reference dictionary, as compiled in the last but one pass of the reference dic‐\ntionary compilation phase; (at the start of the first pass, this file is created\nempty; in successive passes, it contains the reference dictionary entries, as col‐\nlected in the preceding pass).\n\nIf the --reference-dictionary=name option is specified, this intermediate file becomes\npermanent, and is named name, rather than pdf$$.ref.\n\npdf$$.cmp\nUsed to collect reference dictionary entries during the active pass of the reference\ndictionary compilation phase. At the end of any pass, when the content of pdf$$.cmp\ncompares as identical to pdf$$.ref, (or the corresponding file named by the\n--reference-dictionary=name option), then reference dictionary compilation is termi‐\nnated, and the document reference map is appended to this intermediate file, for in‐\nclusion in the final formatting passes.\n\npdf$$.tc\nAn intermediate PostScript file, in which “Table of Contents” entries are collected,\nto facilitate relocation before the body text, on ultimate output to the Ghostscript\npostprocessor.\n\npdf$$.ps\nAn intermediate PostScript file, in which the body text is collected prior to ultimate\noutput to the Ghostscript postprocessor, in the proper sequence, after pdf$$.tc.\n", "subsections": [] }, "Authors": { "content": "pdfroff was written by Keith Marshall, who maintains it at his groff-pdfmark OSDN site.\ngroff's version may be withdrawn in a future release.\n\nSee also\nGroff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary\ngroff manual. You can browse it interactively with “info groff”.\n\nSince pdfroff provides a superset of all groff capabilities, the above manual, or its terser\nreference page, groff(7) may also be considered definitive references to all standard capa‐\nbilities of pdfroff, with this document providing the reference to pdfroff's extended fea‐\ntures.\n\nWhile pdfroff imposes neither any restriction on, nor any requirement for, the use of any\nspecific groff macro package, a number of supplied macro packages, and in particular those\nassociated with the package pdfmark.tmac, are best suited for use with pdfroff as the pre‐\nferred formatter.\n\n/usr/share/doc/groff-base/pdf/pdfmark.pdf.gz\n“Portable Document Format Publishing with GNU Troff”, by Keith Marshall, offers de‐\ntailed documentation on the use of these packages. This file, together with its\nsource, pdfmark.ms, is part of the groff distribution.\n\ngroff 1.23.0 31 March 2024 pdfroff(1)", "subsections": [] } }, "flags": [], "examples": [], "see_also": [] }