| blob | ce834f2e5ffabc055046e10eea35e97e7b7f7935 |
1 .TH PDFROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
2 .\" --------------------------------------------------------------------
3 .\" Legal Matters
4 .\" --------------------------------------------------------------------
5 .ig
6 pdfroff.1
8 File position: <groff-source>/contrib/pdfmark/pdfroff.man
10 Last update:
12 This file is part of groff, the GNU roff type-setting system.
14 Copyright (C) 2005 Free Software Foundation, Inc.
15 written by Keith Marshall <keith.d.marshall@ntlworld.com>
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.1 or
19 any later version published by the Free Software Foundation; with no
20 Front-Cover Texts, no Back-Cover Texts, and the following Invariant
21 Sections:--
23 a) This "Legal Matters" section, extending from the start of
24 the document, to the end of the enclosing ".ig" section.
26 b) The entire section bearing the heading "AUTHOR", extending
27 from the ".SH AUTHOR" tag, to the end of the document.
29 A copy of the Free Documentation License is included as a file called
30 FDL in the main directory of the groff source package.
31 ..
32 .\" --------------------------------------------------------------------
33 .
34 .SH NAME
35 pdfroff \- create PDF documents using
36 .I groff
37 .
38 .hw pdfmark
39 .de Q
40 \&\\$3\*(lq\\$1\*(rq\\$2
41 ..
42 .de nohy
43 .hy 0
44 \&\\$*
45 .hy
46 ..
47 .\" --------------------------------------------------------------------
48 .
49 .SH SYNOPSIS
50 .de cmd
51 . if r@i .in
52 . nr @i \\n(.i
53 . in +\w'\f[B]\\$1\0'u
54 . ti \\n(@iu
55 . B \\$1\0\c
56 ..
57 .de opt
58 . tr -\-
59 . RB [ -\\$1\c
60 . IR \&\\$2 ]
61 . tr --
62 ..
63 .de opta
64 . ie \\n(.$>1 .opt \\$1 \0\\$2
65 . el .opt \\$1
66 ..
67 .de optx
68 . tr -\-
69 . RB [ --no\\$1 \0|\0\c
70 . B -\\$1\c
71 . IR \&\\$2 ]
72 . tr --
73 ..
74 .ad l
75 .hy 0
76 .ll -5
77 .cmd pdfroff
78 .opt abcegilpstzCEGNRSUVXZ
79 .opta d cs
80 .opta f fam
81 .opta F dir
82 .opta I dir
83 .opta L arg
84 .opta m name
85 .opta M dir
86 .opta n num
87 .opta o list
88 .opta P arg
89 .opta r cn
90 .opta T dev
91 .opta w name
92 .opta W name
93 .opt -no-toc-relocation
94 .opt -stylesheet= name
95 .optx -pdf-output= name
96 .optx -reference-dictionary= name
97 .opt -report-progress
98 .B file
99 .I ...
100 .ll
101 .sp
102 .cmd pdfroff
103 .B -h
104 |
105 .B --help
106 .sp
107 .cmd pdfroff
108 .B -v
109 |
110 .B --version
111 .RI [ option
112 .IR ... ]
113 .rr @i
114 .in
115 .ad
116 .hy
117 .P
118 The command line is parsed in accordance with normal GNU conventions,
119 but with one exception \(em when specifying any short form option
120 (i.e., a single character option introduced by a single hyphen),
121 and if that option expects an argument, then it
122 .I must
123 be specified independently (i.e., it may
124 .I not
125 be appended to any group of other single character short form options).
126 .P
127 Long form option names (i.e., those introduced by a double hyphen)
128 may be abbreviated to their minimum length unambigous initial substring.
129 .
130 .\" --------------------------------------------------------------------
131 .
132 .SH DESCRIPTION
133 .B pdfroff
134 is a wrapper program for the GNU text processing system,
135 .BR groff .
136 It transparently handles the mechanics of multiple pass
137 .B groff
138 processing, when applied to suitably marked up
139 .B groff
140 source files,
141 such that tables of contents and body text are formatted separately,
142 and are subsequently combined in the correct order, for final publication
143 as a single PDF document.
144 A further optional
145 .Q style\0sheet
146 capability is provided;
147 this allows for the definition of content which is required to preceed the
148 table of contents, in the published document.
149 .P
150 For each invocation of
151 .BR pdfroff ,
152 the ultimate
153 .B groff
154 output stream is post\(hyprocessed by the GhostScript interpreter,
155 to produce a finished PDF document.
156 .P
157 .B pdfroff
158 makes no assumptions about, and imposes no restrictions on,
159 the use of any
160 .B groff
161 macro packages which the user may choose to employ,
162 in order to achieve a desired document format;
163 however, it
164 .I does
165 include specific built in support for the
166 .B pdfmark
167 macro package, should the user choose to employ it.
168 Specifically, if the
169 .I pdfhref
170 macro, defined in the
171 .B pdfmark.tmac
172 package, is used to define public reference marks,
173 or dynamic links to such reference marks, then
174 .B pdfroff
175 will perform as many preformatting
176 .B groff
177 passes as required, up to a maximum limit of
178 .IR four ,
179 in order to compile a document reference dictionary,
180 to resolve references, and to expand the dynamically defined
181 content of links.
182 .
183 .\" --------------------------------------------------------------------
184 .
185 .SH USAGE
186 .B pdfroff
187 usage closely mirrors that of
188 .B groff
189 itself.
190 Indeed,
191 with the exception of the
192 .BR \-h ,
193 .BR \-v ,
194 and
195 .BI \-T \0dev
196 short form options, and
197 all long form options,
198 which are parsed internally by
199 .BR pdfroff ,
200 all options and file name arguments specified on the command line are
201 passed on to
202 .BR groff ,
203 to control the formatting of the PDF document.
204 Consequently,
205 .B pdfroff
206 accepts all options and arguments, as specified in
207 .BR groff (@MAN1EXT@),
208 which may also be considered as the definitive reference for all standard
209 .BR pdfroff
210 options and argument usage.
211 .
212 .\" --------------------------------------------------------------------
213 .
214 .SH OPTIONS
215 .B pdfroff
216 accepts all of the short form options
217 (i.e., those introduced by a single hyphen),
218 which are available with
219 .B groff
220 itself.
221 In most cases, these are simply passed transparently to
222 .BR groff ;
223 the following, however, are handled specially by
224 .BR pdfroff .
225 .TP
226 .B \-h
227 Same as
228 .BR \-\-help ;
229 see below.
230 .TP
231 .B \-i
232 Process standard input, after all other specified input files.
233 This is passed transparently to
234 .BR groff ,
235 but, if grouped with other options, it
236 .I must
237 be the first in the group.
238 Hiding it within a group will
239 break standard input processing, in the multiple pass
240 .B groff
241 processing context of
242 .BR pdfroff .
243 .TP
244 .BI \-T \0dev
245 Only
246 .BI \-T \0ps
247 is supported by
248 .BR pdfroff .
249 Attempting to specify any other device will cause
250 .B pdfroff
251 to abort.
252 .TP
253 .B \-v
254 Same as
255 .BR \-\-version ;
256 see below.
257 .P
258 See
259 .BR groff (@MAN1EXT@)
260 for a description of all other short form options,
261 which are transparently passed through
262 .BR pdfroff
263 to
264 .BR groff .
265 .P
266 All long form options
267 (i.e., those introduced by a double hyphen)
268 are interpreted locally by
269 .BR pdfroff ;
270 they are
271 .B not
272 passed on to
273 .BR groff ,
274 unless otherwise stated below.
275 .TP
276 .B \-\-help
277 Causes
278 .B pdfroff
279 to display a summary of the its usage syntax, and supported options,
280 and then exit.
281 .TP
282 .B \-\-no\-pdf\-output
283 May be used with the
284 .BI \-\-reference\-dictionary= name
285 option (described below) to eliminate the overhead of PDF formatting,
286 when running
287 .B pdfroff
288 to create a reference dictionary, for use in a different document.
289 .TP
290 .B \-\-no\-reference\-dictionary
291 May be used to eliminate the overhead of creating a reference dictionary,
292 when it is known that the target PDF document will contain no public
293 references, created by the
294 .I pdfhref
295 macro.
296 .TP
297 .B \-\-no\-toc\-relocation
298 May be used to eliminate the extra
299 .B groff
300 processing pass,
301 which is required to generate a table of contents,
302 and relocate it to the start of the PDF document,
303 when processing any document which lacks an automatically
304 generated table of contents.
305 .TP
306 .BI \-\-pdf\-output= name
307 Specifies the name to be used for the resultant PDF document;
308 if unspecified, the PDF output is written to standard output.
309 A future version of
310 .B pdfroff
311 may use this option,
312 to encode the document name in a generated reference dictionary.
313 .TP
314 .BI \-\-reference\-dictionary= name
315 Specifies the name to be used for the generated reference dictionary file;
316 if unspecified, the reference dictionary is created in a temporary file,
317 which is deleted when
318 .B pdfroff
319 completes processing of the current document.
320 This option
321 .I must
322 be specified, if it is desired to save the reference dictionary,
323 for use in references placed in other PDF documents.
324 .TP
325 .B \-\-report\-progress
326 Causes
327 .B pdfroff
328 to display an informational message on standard error,
329 at the start of each
330 .B groff
331 processing pass.
332 .TP
333 .BI \-\-stylesheet= name
334 Specifies the name of an
335 .IR "input file" ,
336 to be used as a style sheet for formatting of content,
337 which is to be placed
338 .I before
339 the table of contents,
340 in the formatted PDF document.
341 .TP
342 .B \-\-version
343 Causes
344 .B pdfroff
345 to display a version identification message.
346 The entire command line is then passed transparently to
347 .BR groff ,
348 in a
349 .I one
350 pass operation
351 .IR only ,
352 in order to display the associated
353 .B groff
354 version information, before exiting.
355 .
356 .\" --------------------------------------------------------------------
357 .
358 .SH ENVIRONMENT
359 The following environment variables may be set, and exported,
360 to modify the behaviour of
361 .BR pdfroff .
362 .TP
363 .B GROFF_TMPDIR
364 Identifies the directory in which
365 .B pdfroff
366 should create temporary files.
367 If
368 .B GROFF_TMPDIR
369 is
370 .I not
371 specified, then the variables
372 .BR TMPDIR ,
373 .B TMP
374 and
375 .B TEMP
376 are considered in turn, as possible temporary file repositories.
377 If none of these are set, then temporary files will be created
378 in the current directory.
379 .TP
380 .B GROFF_GHOSTSCRIPT_INTERPRETER
381 Specifies the program to be invoked, when
382 .B pdfroff
383 converts
384 .B groff
385 PostScript output to PDF.
386 If
387 .B GROFF_GHOSTSCRIPT_INTERPRETER
388 is not specified, then
389 .B pdfroff
390 will search the process
391 .BR PATH ,
392 looking for a program with any of the well known names
393 for the GhostScript interpreter;
394 if no GhostScript interpreter can be found,
395 .B pdfroff
396 will abort.
397 .TP
398 .B GROFF_AWK_INTERPRETER
399 Specifies the program to be invoked, when
400 .B pdfroff
401 is extracting reference dictionary entries from a
402 .B groff
403 intermediate message stream.
404 If
405 .B GROFF_AWK_INTERPRETER
406 is not specified, then
407 .B pdfroff
408 will search the process
409 .BR PATH ,
410 looking for any of the preferred programs, `gawk', `mawk', `nawk'
411 and `awk', in this order;
412 if none of these are found,
413 .B pdfroff
414 will issue a warning message, and continue processing;
415 however, in this case, no reference dictionary will be created.
416 .TP
417 .B SHOW_PROGRESS
418 If this is set to a non-empty value, then
419 .B pdfroff
420 will always behave as if the
421 .B \-\-report\-progress
422 option is specified, on the command line.
423 .
424 .\" --------------------------------------------------------------------
425 .
426 .SH FILES
427 Input and output files for
428 .B pdfroff
429 may be named according to any convention of the user's choice.
430 Typically, input files may be named according to the choice of the
431 principal formatting macro package, e.g.,
432 .IB file .ms
433 might be an input file for formatting using the
434 .B ms
435 macros
436 .RB ( s.tmac );
437 normally, the final output file should be named
438 .IB file .pdf\c
439 \&.
440 .P
441 Temporary files, created by
442 .BR pdfroff ,
443 are placed in the directory specified by environment variables (see
444 section
445 .BR ENVIRONMENT ),
446 and named according to the convention
447 .BI pdf $$ .*\c
448 \&, where
449 .I $$
450 is the standard shell variable representing the process ID of the
451 .B pdfroff
452 process itself, and
453 .I *
454 represents any of a number of extensions used by
455 .B pdfroff
456 for temporary and intermediate files.
457 .
458 .\" --------------------------------------------------------------------
459 .
460 .SH SEE ALSO
461 See
462 .BR groff (@MAN1EXT@)
463 for the definitive reference to document formatting with
464 .BR groff .
465 Since
466 .B pdfroff
467 provides a superset of all
468 .B groff
469 capabilities,
470 .BR groff (@MAN1EXT@)
471 may also be considered to be the definitive reference to all
472 .I standard
473 capabilities of
474 .BR pdfroff ,
475 with this document providing the reference to
476 .BR pdfroff 's
477 extended features.
478 .P
479 While
480 .B pdfroff
481 imposes neither any restriction on, nor any requirement for,
482 the use of any specific
483 .B groff
484 macro package, a number of supplied macro packages,
485 and in particular those associated with the package
486 .BR pdfmark.tmac ,
487 are best suited for use with
488 .BR pdfroff
489 as the preferred formatter.
490 Detailed documentation on the use of these packages may be found,
491 in PDF format, in the reference guide
492 .BR "\*(lqPortable Document Format Publishing with GNU Troff\*(rq" ,
493 included in the installed documentation set as
494 .hy 0
495 .BR @PDFDOCDIR@/pdfmark.pdf .
496 .hy
497 .
498 .\" --------------------------------------------------------------------
499 .
500 .SH AUTHOR
501 Copyright \(co 2005, Free Software Foundation, Inc.
502 .LP
503 This man page is distributed under the terms of the
504 GNU Free Documentation License (FDL), version 1.1 or later,
505 and is part of the
506 .I GNU troff
507 software package.
508 It was originally written by Keith Marshall,
509 .nohy <keith.d.marshall@ntlworld.com>,
510 who also wrote the implementation of the
511 .I pdfroff
512 program, to which it relates.
513 .LP
514 You should have received a copy of the FDL as part of the
515 .I GNU troff
516 distribution; it is also available on\-line, at the GNU
517 .Q copyleft
518 site,
519 .nohy <http://www.gnu.org/copyleft/fdl.html>.
520 .
521 .\" --------------------------------------------------------------------
522 .\" EOF / vim: ft=groff