pdfroff(1)

1PDFROFF(1)                  General Commands Manual                 PDFROFF(1)
2
3
4

NAME

6       pdfroff - create PDF documents using groff
7

SYNOPSIS

9       pdfroff [-abcegilpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir] [-I dir]
10               [-L arg] [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn]
11               [-T dev] [-w name] [-W name] [--emit-ps] [--no-toc-relocation]
12               [--no-kill-null-pages] [--stylesheet=name] [--no-pdf-output]
13               [--pdf-output=name] [--no-reference-dictionary]
14               [--reference-dictionary=name] [--report-progress]
15               [--keep-temporary-files] [file ...]
16
17       pdfroff -h
18       pdfroff --help
19
20       pdfroff -v [groff-option ...]
21       pdfroff --version [groff-option ...]
22

DESCRIPTION

24       pdfroff is a wrapper program for the GNU text processing system, groff.
25       It transparently handles the mechanics of multiple pass groff  process‐
26       ing,  when  applied to suitably marked up groff source files, such that
27       tables of contents and body text are formatted separately, and are sub‐
28       sequently  combined  in  the  correct order, for final publication as a
29       single PDF document.  A further optional “style  sheet”  capability  is
30       provided;  this  allows for the definition of content which is required
31       to precede the table of contents, in the published document.
32
33       For each invocation of pdfroff, the ultimate  groff  output  stream  is
34       post-processed  by  the  GhostScript interpreter, to produce a finished
35       PDF document.
36
37       pdfroff makes no assumptions about, and imposes no restrictions on, the
38       use of any groff macro packages which the user may choose to employ, in
39       order to achieve a desired document format; however,  it  does  include
40       specific  built  in  support  for the pdfmark macro package, should the
41       user choose to employ it.  Specifically, if the pdfhref macro,  defined
42       in  the pdfmark.tmac package, is used to define public reference marks,
43       or dynamic links to such reference marks, then pdfroff performs as many
44       preformatting  groff passes as required, up to a maximum limit of four,
45       in order to compile a document reference dictionary, to resolve  refer‐
46       ences, and to expand the dynamically defined content of links.
47

USAGE

49       The  command  line is parsed in accordance with normal GNU conventions,
50       but with one exception — when specifying any short form option (i.e., a
51       single character option introduced by a single hyphen), and if that op‐
52       tion expects an argument,  then  it  must  be  specified  independently
53       (i.e.,  it  may  not be appended to any group of other single character
54       short form options).
55
56       Long form option names (i.e., those introduced by a double hyphen)  may
57       be abbreviated to their minimum length unambiguous initial substring.
58
59       Otherwise, pdfroff usage closely mirrors that of groff itself.  Indeed,
60       with the exception of the -h, -v, and -T dev short  form  options,  and
61       all  long form options, which are parsed internally by pdfroff, all op‐
62       tions and file name arguments specified on the command line are  passed
63       on  to  groff,  to  control the formatting of the PDF document.  Conse‐
64       quently, pdfroff accepts all options and  arguments,  as  specified  in
65       groff(1),  which may also be considered as the definitive reference for
66       all standard pdfroff options and argument usage.
67

OPTIONS

69       pdfroff accepts all of the short form options (i.e.,  those  introduced
70       by  a  single  hyphen), which are available with groff itself.  In most
71       cases, these are simply passed transparently to groff;  the  following,
72       however, are handled specially by pdfroff.
73
74       -h     Same as --help; see below.
75
76       -i     Process  standard  input, after all other specified input files.
77              This is passed transparently to  groff,  but,  if  grouped  with
78              other  options,  it  must  be the first in the group.  Hiding it
79              within a group breaks standard input processing, in the multiple
80              pass groff processing context of pdfroff.
81
82       -T dev Only  -T ps  is supported by pdfroff.  Attempting to specify any
83              other device causes pdfroff to abort.
84
85       -v     Same as --version; see below.
86
87       See groff(1) for a description of all other short form  options,  which
88       are transparently passed through pdfroff to groff.
89
90       All  long  form options (i.e., those introduced by a double hyphen) are
91       interpreted locally by pdfroff; they are not passed on to groff, unless
92       otherwise stated below.
93
94       --help Causes pdfroff to display a summary of the its usage syntax, and
95              supported options, and then exit.
96
97       --emit-ps
98              Suppresses the final output conversion step, causing pdfroff  to
99              emit  PostScript  output instead of PDF.  This may be useful, to
100              capture intermediate PostScript output, when using a specialised
101              postprocessor, such as gpresent for example, in place of the de‐
102              fault GhostScript PDF writer.
103
104       --keep-temporary-files
105              Suppresses the deletion of temporary files, which  normally  oc‐
106              curs  after  pdfroff has completed PDF document formatting; this
107              may be useful, when debugging formatting problems.
108
109              See section “Files” below for a  description  of  the  temporary
110              files used by pdfroff.
111
112       --no-pdf-output
113              May  be  used  with  the --reference-dictionary=name option (de‐
114              scribed below) to eliminate the overhead of PDF formatting, when
115              running  pdfroff  to create a reference dictionary, for use in a
116              different document.
117
118       --no-reference-dictionary
119              May be used to eliminate the overhead of  creating  a  reference
120              dictionary,  when  it is known that the target PDF document con‐
121              tains no public references, created by the pdfhref macro.
122
123       --no-toc-relocation
124              May be used to eliminate the extra groff processing pass,  which
125              is  required to generate a table of contents, and relocate it to
126              the start of the PDF  document,  when  processing  any  document
127              which lacks an automatically generated table of contents.
128
129       --no-kill-null-pages
130              While  preparing  for  simulation  of the manual collation step,
131              which is traditionally required to relocate a table of  contents
132              to  the  start  of  a  document, pdfroff accumulates a number of
133              empty page descriptions into the intermediate PostScript  output
134              stream.   During the final collation step, these empty pages are
135              normally discarded  from  the  finished  document;  this  option
136              forces pdfroff to leave them in place.
137
138       --pdf-output=name
139              Specifies the name to be used for the resultant PDF document; if
140              unspecified, the PDF output is written to  standard  output.   A
141              future  version  of  pdfroff  may use this option, to encode the
142              document name in a generated reference dictionary.
143
144       --reference-dictionary=name
145              Specifies the name to be used for the generated  reference  dic‐
146              tionary  file;  if unspecified, the reference dictionary is cre‐
147              ated in a temporary file, which is  deleted  when  pdfroff  com‐
148              pletes  processing of the current document.  This option must be
149              specified, if it is desired to save  the  reference  dictionary,
150              for use in references placed in other PDF documents.
151
152       --report-progress
153              Causes  pdfroff  to display an informational message on standard
154              error, at the start of each groff processing pass.
155
156       --stylesheet=name
157              Specifies the name of an input file, to be used as a style sheet
158              for  formatting of content, which is to be placed before the ta‐
159              ble of contents, in the formatted PDF document.
160
161       --version
162              Causes pdfroff to display a version identification message.  The
163              entire  command line is then passed transparently to groff, in a
164              one pass operation only, in  order  to  display  the  associated
165              groff version information, before exiting.
166

ENVIRONMENT

168       The following environment variables may be set, and exported, to modify
169       the behaviour of pdfroff.
170
171       PDFROFF_COLLATE
172              Specifies the program to be used for collation of  the  finished
173              PDF document.
174
175              This  collation  step may be required to move tables of contents
176              to the start of the finished PDF document, when formatting  with
177              traditional  macro  packages, which print them at the end.  How‐
178              ever, users should not normally need to specify PDFROFF_COLLATE,
179              (and  indeed,  are  not  encouraged  to do so).  If unspecified,
180              pdfroff uses sed(1) by default, which normally suffices.
181
182              If PDFROFF_COLLATE is specified, then it must act as  a  filter,
183              accepting a list of file name arguments, and write its output to
184              the   stdout   stream,   whence   it    is    piped    to    the
185              PDFROFF_POSTPROCESSOR_COMMAND,  to produce the finished PDF out‐
186              put.
187
188              When specifying PDFROFF_COLLATE, it  is  normally  necessary  to
189              also specify PDFROFF_KILL_NULL_PAGES.
190
191              PDFROFF_COLLATE  is  ignored,  if  pdfroff  is  invoked with the
192              --no-kill-null-pages option.
193
194       PDFROFF_KILL_NULL_PAGES
195              Specifies options to be passed to the PDFROFF_COLLATE program.
196
197              It   should   not   normally    be    necessary    to    specify
198              PDFROFF_KILL_NULL_PAGES.   The  internal  default  is  a  sed(1)
199              script, which is intended to remove completely blank pages  from
200              the  collated  output stream, and which should be appropriate in
201              most applications of pdfroff.  However, if  any  alternative  to
202              sed(1)  is specified for PDFROFF_COLLATE, then it is likely that
203              a     corresponding      alternative      specification      for
204              PDFROFF_KILL_NULL_PAGES is required.
205
206              As  in  the  case of PDFROFF_COLLATE, PDFROFF_KILL_NULL_PAGES is
207              ignored, if pdfroff is invoked with the --no-kill-null-pages op‐
208              tion.
209
210       PDFROFF_POSTPROCESSOR_COMMAND
211              Specifies  the command to be used for the final document conver‐
212              sion from PostScript intermediate output to PDF.  It must behave
213              as  a  filter, writing its output to the stdout stream, and must
214              accept an arbitrary number of files ... arguments, with the spe‐
215              cial case of - representing the stdin stream.
216
217              If unspecified, PDFROFF_POSTPROCESSOR_COMMAND defaults to
218                   gs -dBATCH -dQUIET -dNOPAUSE -dSAFER -sDEVICE=pdfwrite \
219                        -sOutputFile=-
220
221       GROFF_TMPDIR
222              Identifies the directory in which pdfroff should create a subdi‐
223              rectory for its temporary files.  If GROFF_TMPDIR is not  speci‐
224              fied,  then the variables TMPDIR, TMP and TEMP are considered in
225              turn, as possible temporary file repositories.  If none of these
226              are  set,  then temporary files are created in a subdirectory of
227              /tmp.
228
229       GROFF_GHOSTSCRIPT_INTERPRETER
230              Specifies the program to be invoked, when pdfroff converts groff
231              PostScript  output  to PDF.  If PDFROFF_POSTPROCESSOR_COMMAND is
232              specified, then the command name it specifies is implicitly  as‐
233              signed to GROFF_GHOSTSCRIPT_INTERPRETER, overriding any explicit
234              setting     specified     in      the      environment.       If
235              GROFF_GHOSTSCRIPT_INTERPRETER  is  not  specified,  then pdfroff
236              searches the process PATH, looking for a program with any of the
237              well  known  names for the GhostScript interpreter; if no Ghost‐
238              Script interpreter can be found, pdfroff aborts.
239
240       GROFF_AWK_INTERPRETER
241              Specifies the program to be invoked, when pdfroff is  extracting
242              reference  dictionary  entries from a groff intermediate message
243              stream.  If GROFF_AWK_INTERPRETER is not specified, then pdfroff
244              searches the process PATH, looking for any of the preferred pro‐
245              grams, ‘gawk’, ‘mawk’, ‘nawk’, and ‘awk’, in this order; if none
246              of  these  are found, pdfroff issues a warning message, and con‐
247              tinue processing; however, in this case, no reference dictionary
248              is created.
249
250       OSTYPE Typically  defined automatically by the operating system, OSTYPE
251              is used on Microsoft Win32/MS-DOS platforms only, to  infer  the
252              default PATH_SEPARATOR character, which is used when parsing the
253              process PATH to search for external helper programs.
254
255       PATH_SEPARATOR
256              If set, PATH_SEPARATOR overrides the default  separator  charac‐
257              ter,  (‘:’ on POSIX/Unix systems, inferred from OSTYPE on Micro‐
258              soft Win32/MS-DOS), which is used when parsing the process  PATH
259              to search for external helper programs.
260
261       SHOW_PROGRESS
262              If this is set to a non-empty value, then pdfroff always behaves
263              as if the --report-progress option is specified, on the  command
264              line.
265

FILES

267       Input  and  output files for pdfroff may be named according to any con‐
268       vention of the user's choice.  Typically, input files may be named  ac‐
269       cording  to the choice of the principal formatting macro package, e.g.,
270       file.ms might be an input file  for  formatting  using  the  ms  macros
271       (s.tmac); normally, the final output file should be named file.pdf.
272
273       Temporary  files, created by pdfroff, are placed in the file system hi‐
274       erarchy, in or below the directory specified by  environment  variables
275       (see  section  “Environment”  above).  If mktemp(1) is available, it is
276       invoked to create a private subdirectory  of  the  nominated  temporary
277       files  directory,  (with  subdirectory  name  derived from the template
278       pdfroff-XXXXXXXXXX); if this subdirectory is successfully created,  the
279       temporary files will be placed within it, otherwise they will be placed
280       directly in the directory nominated in the environment.
281
282       All temporary files themselves are named according  to  the  convention
283       pdf$$.*,  where  $$  is  the  standard  shell variable representing the
284       process ID of the pdfroff process itself, and * represents any  of  the
285       extensions  used by pdfroff to identify the following temporary and in‐
286       termediate files.
287
288       pdf$$.tmp
289              A scratch pad file, used to capture reference  data  emitted  by
290              groff, during the reference dictionary compilation phase.
291
292       pdf$$.ref
293              The  reference  dictionary, as compiled in the last but one pass
294              of the reference dictionary compilation phase; (at the start  of
295              the  first  pass,  this  file  is  created  empty; in successive
296              passes, it contains the reference dictionary  entries,  as  col‐
297              lected in the preceding pass).
298
299              If the --reference-dictionary=name option is specified, this in‐
300              termediate file becomes permanent, and  is  named  name,  rather
301              than pdf$$.ref.
302
303       pdf$$.cmp
304              Used  to  collect reference dictionary entries during the active
305              pass of the reference dictionary compilation phase.  At the  end
306              of any pass, when the content of pdf$$.cmp compares as identical
307              to  pdf$$.ref,  (or  the  corresponding  file   named   by   the
308              --reference-dictionary=name  option),  then reference dictionary
309              compilation is terminated, and the document reference map is ap‐
310              pended  to  this  intermediate  file, for inclusion in the final
311              formatting passes.
312
313       pdf$$.tc
314              An intermediate PostScript file, in which  “Table  of  Contents”
315              entries  are collected, to facilitate relocation before the body
316              text, on ultimate output to the GhostScript postprocessor.
317
318       pdf$$.ps
319              An intermediate PostScript file, in which the body text is  col‐
320              lected  prior  to ultimate output to the GhostScript postproces‐
321              sor, in the proper sequence, after pdf$$.tc.
322

AUTHORS

324       pdfroff was written by Keith Marshall ⟨keith.d.marshall@ntlworld.com⟩.
325