/contrib/groff/contrib/pdfmark/pdfroff.man

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