| blob | f956b783db494426d4f3e6a48a413643b0cb7373 |
1 .TH @U_PDFROFF@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
2 .ig
3 @ pdfroff.1.in
5 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
7 Copyright (C) 2005 - 2007 Free Software Foundation, Inc.
8 written by Keith Marshall <keith.d.marshall@ntlworld.com>
10 Permission is granted to copy, distribute and/or modify this document
11 under the terms of the GNU Free Documentation License, Version 1.1 or
12 any later version published by the Free Software Foundation; with no
13 Front-Cover Texts, no Back-Cover Texts, and the following Invariant
14 Sections:--
16 a) This "Legal Matters" section, extending from the start of
17 the document, to the end of the enclosing ".ig" section.
19 b) The entire section bearing the heading "AUTHOR", extending
20 from the ".SH AUTHOR" tag, to the end of the document.
22 You should have received a copy of the Free Documentation License
23 as part of the file COPYING; also located in the main directory of the
24 source package of this program.
25 ..
26 .
27 .
28 .\"
29 .\" Local macro definitions
30 .
31 .hw pdfmark
32 .
33 .de NH
34 . hy 0
35 \&\\$*
36 . hy
37 ..
38 .
39 .
40 .\"
41 .
42 .SH NAME
43 .
44 @L_PDFROFF@ \- create PDF documents using @T_ROFF@
45 .
46 .
47 .\"
48 .
49 .SH SYNOPSIS
50 .
51 .SY @L_PDFROFF@
52 .OP \-abcegilpstzCEGNRSUVXZ
53 .OP \-d cs
54 .OP \-f fam
55 .OP \-F dir
56 .OP \-I dir
57 .OP \-L arg
58 .OP \-m name
59 .OP \-M dir
60 .OP \-n num
61 .OP \-o list
62 .OP \-P arg
63 .OP \-r cn
64 .OP \-T dev
65 .OP \-w name
66 .OP \-W name
67 .OP \-\-emit\-ps
68 .OP \-\-no\-toc\-relocation
69 .OP \-\-no-kill\-null\-pages
70 .OP \-\-stylesheet=\fIname\fP
71 .OP \-\-no\-pdf\-output
72 .OP \-\-pdf\-output=\fIname\fP
73 .OP \-\-no\-reference\-dictionary
74 .OP \-\-reference\-dictionary=\fIname\fP
75 .OP \-\-report\-progress
76 .OP \-\-keep\-temporary\-files
77 .I file .\|.\|.
78 .
79 .SY @L_PDFROFF@
80 .B \-h
81 |
82 .B \-\-help
83 .
84 .SY @L_PDFROFF@
85 .B \-v
86 |
87 .B \-\-version
88 .RI [ option\ .\|.\|. ]
89 .YS
90 .
91 .
92 .\"
93 .
94 .SH DESCRIPTION
95 .
96 .B @L_PDFROFF@
97 is a wrapper program for the @T_ROFF@ text processing system,
98 .BR @L_ROFF@ .
99 It transparently handles the mechanics of multiple pass
100 .B @L_ROFF@
101 processing, when applied to suitably marked up
102 .B @L_ROFF@
103 source files,
104 such that tables of contents and body text are formatted separately,
105 and are subsequently combined in the correct order, for final publication
106 as a single PDF document.
107 A further optional
108 \*(lqstyle sheet\*(rq
109 capability is provided;
110 this allows for the definition of content which is required to precede the
111 table of contents, in the published document.
112 .
113 .P
114 For each invocation of
115 .BR @L_PDFROFF@ ,
116 the ultimate
117 .B @L_ROFF@
118 output stream is post-processed by the GhostScript interpreter,
119 to produce a finished PDF document.
120 .
121 .P
122 .B @L_PDFROFF@
123 makes no assumptions about, and imposes no restrictions on,
124 the use of any
125 .B @L_ROFF@
126 macro packages which the user may choose to employ,
127 in order to achieve a desired document format;
128 however, it
129 .I does
130 include specific built in support for the
131 .B pdfmark
132 macro package, should the user choose to employ it.
133 Specifically, if the
134 .I pdfhref
135 macro, defined in the
136 .B pdfmark.tmac
137 package, is used to define public reference marks,
138 or dynamic links to such reference marks, then
139 .B @L_PDFROFF@
140 performs as many preformatting
141 .B @L_ROFF@
142 passes as required, up to a maximum limit of
143 .IR four ,
144 in order to compile a document reference dictionary,
145 to resolve references, and to expand the dynamically defined
146 content of links.
147 .
148 .
149 .\"
150 .
151 .SH USAGE
152 .
153 The command line is parsed in accordance with normal GNU conventions,
154 but with one exception \(em when specifying any short form option
155 (i.e., a single character option introduced by a single hyphen),
156 and if that option expects an argument, then it
157 .I must
158 be specified independently (i.e., it may
159 .I not
160 be appended to any group of other single character short form options).
161 .
162 .P
163 Long form option names (i.e., those introduced by a double hyphen)
164 may be abbreviated to their minimum length unambiguous initial
165 substring.
166 .
167 .P
168 Otherwise,
169 .B @L_PDFROFF@
170 usage closely mirrors that of
171 .B @L_ROFF@
172 itself.
173 Indeed,
174 with the exception of the
175 .BR \-h ,
176 .BR \-v ,
177 and
178 .BI \-T \ dev
179 short form options, and
180 all long form options,
181 which are parsed internally by
182 .BR @L_PDFROFF@ ,
183 all options and file name arguments specified on the command line are
184 passed on to
185 .BR @L_ROFF@ ,
186 to control the formatting of the PDF document.
187 Consequently,
188 .B @L_PDFROFF@
189 accepts all options and arguments, as specified in
190 .BR @L_ROFF@ (@MAN1EXT@),
191 which may also be considered as the definitive reference for all standard
192 .BR @L_PDFROFF@
193 options and argument usage.
194 .
195 .
196 .\"
197 .
198 .SH OPTIONS
199 .
200 .B @L_PDFROFF@
201 accepts all of the short form options
202 (i.e., those introduced by a single hyphen),
203 which are available with
204 .B @L_ROFF@
205 itself.
206 In most cases, these are simply passed transparently to
207 .BR @L_ROFF@ ;
208 the following, however, are handled specially by
209 .BR @L_PDFROFF@ .
210 .
211 .TP
212 .B \-h
213 Same as
214 .BR \-\-help ;
215 see below.
216 .
217 .TP
218 .B \-i
219 Process standard input, after all other specified input files.
220 This is passed transparently to
221 .BR @L_ROFF@ ,
222 but, if grouped with other options, it
223 .I must
224 be the first in the group.
225 Hiding it within a group
226 breaks standard input processing, in the multiple pass
227 .B @L_ROFF@
228 processing context of
229 .BR @L_PDFROFF@ .
230 .
231 .TP
232 .BI \-T \ dev
233 Only
234 .B \-T\ ps
235 is supported by
236 .BR @L_PDFROFF@ .
237 Attempting to specify any other device causes
238 .B @L_PDFROFF@
239 to abort.
240 .
241 .TP
242 .B \-v
243 Same as
244 .BR \-\-version ;
245 see below.
246 .
247 .P
248 See
249 .BR @L_ROFF@ (@MAN1EXT@)
250 for a description of all other short form options,
251 which are transparently passed through
252 .BR @L_PDFROFF@
253 to
254 .BR @L_ROFF@ .
255 .
256 .P
257 All long form options
258 (i.e., those introduced by a double hyphen)
259 are interpreted locally by
260 .BR @L_PDFROFF@ ;
261 they are
262 .B not
263 passed on to
264 .BR @L_ROFF@ ,
265 unless otherwise stated below.
266 .
267 .TP
268 .B \-\-help
269 Causes
270 .B @L_PDFROFF@
271 to display a summary of the its usage syntax, and supported options,
272 and then exit.
273 .
274 .TP
275 .B \-\-emit\-ps
276 Suppresses the final output conversion step,
277 causing
278 .B @L_PDFROFF@
279 to emit PostScript output instead of PDF.
280 This may be useful,
281 to capture intermediate PostScript output,
282 when using a specialised postprocessor,
283 such as
284 .I gpresent
285 for example,
286 in place of the default
287 .I GhostScript
288 PDF writer.
289 .
290 .TP
291 .B \-\-keep\-temporary\-files
292 Suppresses the deletion of temporary files,
293 which normally occurs after
294 .B @L_PDFROFF@
295 has completed PDF document formatting;
296 this may be useful,
297 when debugging formatting problems.
298 .IP
299 See section
300 .BR FILES ,
301 for a description of the temporary files used by
302 .BR @L_PDFROFF@ .
303 .
304 .TP
305 .B \-\-no\-pdf\-output
306 May be used with the
307 .BI \%\-\-reference\-dictionary= name
308 option (described below) to eliminate the overhead of PDF formatting,
309 when running
310 .B @L_PDFROFF@
311 to create a reference dictionary, for use in a different document.
312 .
313 .TP
314 .B \-\-no\-reference\-dictionary
315 May be used to eliminate the overhead of creating a reference dictionary,
316 when it is known that the target PDF document contains no public
317 references, created by the
318 .I pdfhref
319 macro.
320 .
321 .TP
322 .B \-\-no\-toc\-relocation
323 May be used to eliminate the extra
324 .B @L_ROFF@
325 processing pass,
326 which is required to generate a table of contents,
327 and relocate it to the start of the PDF document,
328 when processing any document which lacks an automatically
329 generated table of contents.
330 .
331 .TP
332 .B \-\-no\-kill\-null\-pages
333 While preparing for simulation of the manual collation step,
334 which is traditionally required to relocate of a
335 .I "table of contents"
336 to the start of a document,
337 .B @L_PDFROFF@
338 accumulates a number of empty page descriptions
339 into the intermediate
340 .I PostScript
341 output stream.
342 During the final collation step,
343 these empty pages are normally discarded from the finished document;
344 this option forces
345 .B @L_PDFROFF@
346 to leave them in place.
347 .
348 .TP
349 .BI \-\-pdf\-output= name
350 Specifies the name to be used for the resultant PDF document;
351 if unspecified, the PDF output is written to standard output.
352 A future version of
353 .B @L_PDFROFF@
354 may use this option,
355 to encode the document name in a generated reference dictionary.
356 .
357 .TP
358 .BI \-\-reference\-dictionary= name
359 Specifies the name to be used for the generated reference dictionary file;
360 if unspecified, the reference dictionary is created in a temporary file,
361 which is deleted when
362 .B @L_PDFROFF@
363 completes processing of the current document.
364 This option
365 .I must
366 be specified, if it is desired to save the reference dictionary,
367 for use in references placed in other PDF documents.
368 .
369 .TP
370 .B \-\-report\-progress
371 Causes
372 .B @L_PDFROFF@
373 to display an informational message on standard error,
374 at the start of each
375 .B @L_ROFF@
376 processing pass.
377 .
378 .TP
379 .BI \-\-stylesheet= name
380 Specifies the name of an
381 .IR "input file" ,
382 to be used as a style sheet for formatting of content,
383 which is to be placed
384 .I before
385 the table of contents,
386 in the formatted PDF document.
387 .
388 .TP
389 .B \-\-version
390 Causes
391 .B @L_PDFROFF@
392 to display a version identification message.
393 The entire command line is then passed transparently to
394 .BR @L_ROFF@ ,
395 in a
396 .I one
397 pass operation
398 .IR only ,
399 in order to display the associated
400 .B @L_ROFF@
401 version information, before exiting.
402 .
403 .
404 .\"
405 .
406 .SH ENVIRONMENT
407 The following environment variables may be set, and exported,
408 to modify the behaviour of
409 .BR @L_PDFROFF@ .
410 .
411 .TP
412 .B @U_PDFROFF@_COLLATE
413 Specifies the program to be used
414 for collation of the finshed PDF document.
415 .IP
416 This collation step may be required to move
417 .I tables of contents
418 to the start of the finished PDF document,
419 when formatting with traditional macro packages,
420 which print them at the end.
421 However,
422 users should not normally need to specify
423 .BR \%@U_PDFROFF@_COLLATE ,
424 (and indeed,
425 are not encouraged to do so).
426 If unspecified,
427 .B @L_PDFROFF@
428 uses
429 .BR sed (@MAN1EXT@)
430 by default,
431 which normally suffices.
432 .IP
433 If
434 .B \%@L_PDFROFF@_COLLATE
435 .I is
436 specified,
437 then it must act as a filter,
438 accepting a list of file name arguments,
439 and write its output to the
440 .I stdout
441 stream,
442 whence it is piped to the
443 .BR \%@U_PDFROFF@_POSTPROCESSOR_COMMAND ,
444 to produce the finished PDF output.
445 .IP
446 When specifying
447 .BR \%@U_PDFROFF@_COLLATE ,
448 it is normally necessary to also specify
449 .BR \%@U_PDFROFF@_KILL_NULL_PAGES .
450 .IP
451 .B \%@U_PDFROFF@_COLLATE
452 is ignored,
453 if
454 .B @L_PDFROFF@
455 is invoked with the
456 .I \%\-\-no\-kill\-null\-pages
457 option.
458 .
459 .TP
460 .B @U_PDFROFF@_KILL_NULL_PAGES
461 Specifies options to be passed to the
462 .B \%@U_PDFROFF@_COLLATE
463 program.
464 .IP
465 It should not normally be necessary to specify
466 .BR \%@U_PDFROFF@_KILL_NULL_PAGES .
467 The internal default is a
468 .BR sed (@MAN1EXT@)
469 script,
470 which is intended to remove completely blank pages
471 from the collated output stream,
472 and which should be appropriate in most applications of
473 .BR @L_PDFROFF@ .
474 However,
475 if any alternative to
476 .BR sed (@MAN1EXT@)
477 is specified for
478 .BR \%@U_PDFROFF@_COLLATE ,
479 then it is likely that a corresponding alternative specification for
480 .B \%@U_PDFROFF@_KILL_NULL_PAGES
481 is required.
482 .IP
483 As in the case of
484 .BR \%@U_PDFROFF@_COLLATE ,
485 .B \%@U_PDFROFF@_KILL_NULL_PAGES
486 is ignored,
487 if
488 .B @L_PDFROFF@
489 is invoked with the
490 .I \%\-\-no\-kill\-null\-pages
491 option.
492 .
493 .TP
494 .B @U_PDFROFF@_POSTPROCESSOR_COMMAND
495 Specifies the command to be used for the final document conversion
496 from PostScript intermediate output to PDF.
497 It must behave as a filter,
498 writing its output to the
499 .I stdout
500 stream,
501 and must accept an arbitrary number of
502 .I files .\|.\|.\&
503 arguments,
504 with the special case of
505 .I \-
506 representing the
507 .I stdin
508 stream.
509 .IP
510 If unspecified,
511 .B \%@U_PDFROFF@_POSTPROCESSOR_COMMAND
512 defaults to
513 .
514 .RS 2
515 .IP
516 .I
517 .ad l
518 .NH gs \-dBATCH \-dQUIET \-dNOPAUSE \-sDEVICE=pdfwrite \-sOutputFile=\-
519 .ad
520 .RE
521 .
522 .TP
523 .B @U_ROFF@_GHOSTSCRIPT_INTERPRETER
524 Specifies the program to be invoked, when
525 .B @L_PDFROFF@
526 converts
527 .B groff
528 PostScript output to PDF.
529 If
530 .B \%@U_PDFROFF@_POSTPROCESSOR_COMMAND
531 is specified,
532 then the command name it specifies is
533 .I implicitly
534 assigned to
535 .BR \%@U_ROFF@_GHOSTSCRIPT_INTERPRETER ,
536 overriding any explicit setting specified in the environment.
537 If
538 .B \%@U_ROFF@_GHOSTSCRIPT_INTERPRETER
539 is not specified, then
540 .B @L_PDFROFF@
541 searches the process
542 .BR PATH ,
543 looking for a program with any of the well known names
544 for the GhostScript interpreter;
545 if no GhostScript interpreter can be found,
546 .B @L_PDFROFF@
547 aborts.
548 .
549 .TP
550 .B @U_ROFF@_AWK_INTERPRETER
551 Specifies the program to be invoked, when
552 .B @L_PDFROFF@
553 is extracting reference dictionary entries from a
554 .B @L_ROFF@
555 intermediate message stream.
556 If
557 .B \%@U_ROFF@_AWK_INTERPRETER
558 is not specified, then
559 .B @L_PDFROFF@
560 searches the process
561 .BR PATH ,
562 looking for any of the preferred programs, `gawk', `mawk', `nawk'
563 and `awk', in this order;
564 if none of these are found,
565 .B @L_PDFROFF@
566 issues a warning message, and continue processing;
567 however, in this case, no reference dictionary is created.
568 .
569 .TP
570 .B OSTYPE
571 Typically defined automatically by the operating system,
572 .B OSTYPE
573 is used on Microsoft Win32/MS-DOS platforms
574 .IR only ,
575 to infer the default
576 .B \%PATH_SEPARATOR
577 character,
578 which is used when parsing the process
579 .B PATH
580 to search for external helper programs.
581 .
582 .TP
583 .B PATH_SEPARATOR
584 If set,
585 .B \%PATH_SEPARATOR
586 overrides the default separator character,
587 (`:' on POSIX/UNIX systems,
588 inferred from
589 .B OSTYPE
590 on Microsoft Win32/MS-DOS),
591 which is used when parsing the process
592 .B PATH
593 to search for external helper programs.
594 .
595 .TP
596 .B SHOW_PROGRESS
597 If this is set to a non-empty value, then
598 .B @L_PDFROFF@
599 always behaves as if the
600 .B \%\-\-report\-progress
601 option is specified, on the command line.
602 .
603 .
604 .\"
605 .
606 .SH FILES
607 Input and output files for
608 .B @L_PDFROFF@
609 may be named according to any convention of the user's choice.
610 Typically, input files may be named according to the choice of the
611 principal formatting macro package, e.g.,
612 .IB file .ms
613 might be an input file for formatting using the
614 .B ms
615 macros
616 .RB ( s.tmac );
617 normally, the final output file should be named
618 .IB file .pdf\c
619 \&.
620 .
621 .P
622 Temporary files, created by
623 .BR @L_PDFROFF@ ,
624 are placed in the directory specified by environment variables (see
625 section
626 .BR ENVIRONMENT ),
627 and named according to the convention
628 .BI pdf $$ .*\c
629 \&, where
630 .I $$
631 is the standard shell variable representing the process ID of the
632 .B @L_PDFROFF@
633 process itself, and
634 .I *
635 represents any of the extensions used by
636 .B @L_PDFROFF@
637 to identify the following temporary and intermediate files.
638 .
639 .TP
640 .BI pdf $$ .tmp
641 A scratch pad file,
642 used to capture reference data emitted by
643 .BR @L_ROFF@ ,
644 during the
645 .I reference dictionary
646 compilation phase.
647 .
648 .TP
649 .BI pdf $$ .ref
650 The
651 .IR "reference dictionary" ,
652 as compiled in the last but one pass of the
653 .I reference dictionary
654 compilation phase;
655 (at the start of the first pass,
656 this file is created empty;
657 in successive passes,
658 it contains the
659 .I reference dictionary
660 entries,
661 as collected in the preceding pass).
662 .IP
663 If the
664 .BR \%\-\-reference\-dictionary =\c
665 .I name
666 option is specified,
667 this intermediate file becomes permanent,
668 and is named
669 .IR name ,
670 rather than
671 .BI pdf $$ .ref\c
672 \&.
673 .
674 .TP
675 .BI pdf $$ .cmp
676 Used to collect
677 .I reference dictionary
678 entries during the active pass of the
679 .I reference dictionary
680 compilation phase.
681 At the end of any pass,
682 when the content of
683 .BI pdf $$ .cmp
684 compares as identical to
685 .BI pdf $$ .ref\c
686 \&,
687 (or the corresponding file named by the
688 .BR \%\-\-reference\-dictionary =\c
689 .I name
690 option),
691 then
692 .I reference dictionary
693 compilation is terminated,
694 and the
695 .I document reference map
696 is appended to this intermediate file,
697 for inclusion in the final formatting passes.
698 .
699 .TP
700 .BI pdf $$ .tc
701 An intermediate
702 .I PostScript
703 file,
704 in which \*(lqTable of Contents\*(rq entries are collected,
705 to facilitate relocation before the body text,
706 on ultimate output to the
707 .I GhostScript
708 postprocessor.
709 .
710 .TP
711 .BI pdf $$ .ps
712 An intermediate
713 .I PostScript
714 file,
715 in which the body text is collected prior to ultimate output to the
716 .I GhostScript
717 postprocessor,
718 in the proper sequence,
719 .I after
720 .BI pdf $$ .tc\c
721 \&.
722 .
723 .
724 .\"
725 .
726 .SH SEE ALSO
727 .BR @L_ROFF@ (@MAN1EXT@) .
728 .
729 .\"
730 .
731 .SH AUTHOR
732 Copyright \(co 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
733 .br
734 Copyright \(co 2005 - 2007 Free Software Foundation, Inc.
735 .
736 .P
737 This man page is distributed under the terms of the
738 GNU Free Documentation License (FDL), version 1.1 or later.
739 It was originally written by
740 .MT keith.d.marshall@\:ntlworld.com
741 Keith Marshall
742 .ME ,
743 who also wrote the implementation of the
744 .I @L_PDFROFF@
745 program, to which it relates.
746 .
747 .P
748 You should have received a copy of the FDL as part of the
749 .I @T_ROFF@
750 distribution; it is also available on\-line, at
751 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
752 the GNU copyleft site
753 .UE .
754 .
755 .\" s-ts-mode