Legal Matters
--------------------------------------------------------------------
pdfroff.1 File position: <groff-source>/contrib/pdfmark/pdfroff.man Last update: This file is part of groff, the GNU roff type-setting system. Copyright (C) 2005 Free Software Foundation, Inc. written by Keith Marshall <keith.d.marshall@ntlworld.com> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Front-Cover Texts, no Back-Cover Texts, and the following Invariant Sections:-- a) This "Legal Matters" section, extending from the start of the document, to the end of the enclosing ".ig" section. b) The entire section bearing the heading "AUTHOR", extending from the ".SH AUTHOR" tag, to the end of the document. A copy of the Free Documentation License is included as a file called FDL in the main directory of the groff source package. .. --------------------------------------------------------------------
.
.
The command line is parsed in accordance with normal GNU conventions, but with one exception \(em when specifying any short form option (i.e., a single character option introduced by a single hyphen), and if that option expects an argument, then it must be specified independently (i.e., it may not be appended to any group of other single character short form options).
Long form option names (i.e., those introduced by a double hyphen)
may be abbreviated to their minimum length unambigous initial substring.
.
--------------------------------------------------------------------
.
For each invocation of pdfroff , the ultimate groff output stream is post\(hyprocessed by the GhostScript interpreter, to produce a finished PDF document.
pdfroff makes no assumptions about, and imposes no restrictions on,
the use of any
groff macro packages which the user may choose to employ,
in order to achieve a desired document format;
however, it
does include specific built in support for the
pdfmark macro package, should the user choose to employ it.
Specifically, if the
pdfhref macro, defined in the
pdfmark.tmac package, is used to define public reference marks,
or dynamic links to such reference marks, then
pdfroff will perform as many preformatting
groff passes as required, up to a maximum limit of
four , in order to compile a document reference dictionary,
to resolve references, and to expand the dynamically defined
content of links.
.
--------------------------------------------------------------------
.
.
-h Same as --help ; see below.
-i Process standard input, after all other specified input files. This is passed transparently to groff , but, if grouped with other options, it must be the first in the group. Hiding it within a group will break standard input processing, in the multiple pass groff processing context of pdfroff .
-T \0dev Only -T \0ps is supported by pdfroff . Attempting to specify any other device will cause pdfroff to abort.
-v Same as --version ; see below.
See groff (@MAN1EXT@) for a description of all other short form options, which are transparently passed through pdfroff to groff .
All long form options (i.e., those introduced by a double hyphen) are interpreted locally by pdfroff ; they are not passed on to groff , unless otherwise stated below.
--help Causes pdfroff to display a summary of the its usage syntax, and supported options, and then exit.
--no-pdf-output May be used with the --reference-dictionary= name option (described below) to eliminate the overhead of PDF formatting, when running pdfroff to create a reference dictionary, for use in a different document.
--no-reference-dictionary May be used to eliminate the overhead of creating a reference dictionary, when it is known that the target PDF document will contain no public references, created by the pdfhref macro.
--no-toc-relocation May be used to eliminate the extra groff processing pass, which is required to generate a table of contents, and relocate it to the start of the PDF document, when processing any document which lacks an automatically generated table of contents.
--pdf-output= name Specifies the name to be used for the resultant PDF document; if unspecified, the PDF output is written to standard output. A future version of pdfroff may use this option, to encode the document name in a generated reference dictionary.
--reference-dictionary= name Specifies the name to be used for the generated reference dictionary file; if unspecified, the reference dictionary is created in a temporary file, which is deleted when pdfroff completes processing of the current document. This option must be specified, if it is desired to save the reference dictionary, for use in references placed in other PDF documents.
--report-progress Causes pdfroff to display an informational message on standard error, at the start of each groff processing pass.
--stylesheet= name Specifies the name of an "input file" , to be used as a style sheet for formatting of content, which is to be placed before the table of contents, in the formatted PDF document.
--version Causes
pdfroff to display a version identification message.
The entire command line is then passed transparently to
groff , in a
one pass operation
only , in order to display the associated
groff version information, before exiting.
.
--------------------------------------------------------------------
.
GROFF_TMPDIR Identifies the directory in which pdfroff should create temporary files. If GROFF_TMPDIR is not specified, then the variables TMPDIR , TMP and TEMP are considered in turn, as possible temporary file repositories. If none of these are set, then temporary files will be created in the current directory.
GROFF_GHOSTSCRIPT_INTERPRETER Specifies the program to be invoked, when pdfroff converts groff PostScript output to PDF. If GROFF_GHOSTSCRIPT_INTERPRETER is not specified, then pdfroff will search the process PATH , looking for a program with any of the well known names for the GhostScript interpreter; if no GhostScript interpreter can be found, pdfroff will abort.
GROFF_AWK_INTERPRETER Specifies the program to be invoked, when pdfroff is extracting reference dictionary entries from a groff intermediate message stream. If GROFF_AWK_INTERPRETER is not specified, then pdfroff will search the process PATH , looking for any of the preferred programs, `gawk', `mawk', `nawk' and `awk', in this order; if none of these are found, pdfroff will issue a warning message, and continue processing; however, in this case, no reference dictionary will be created.
OSTYPE Typically defined automatically by the operating system, OSTYPE is used on Microsoft Win32/MS\(hyDOS platforms only , to infer the default PATH_SEPARATOR character, which is used when parsing the process PATH to search for external helper programs.
PATH_SEPARATOR If set, PATH_SEPARATOR overrides the default separator character, (':' on POSIX/UNIX systems, inferred from OSTYPE on Microsoft Win32/MS\(hyDOS), which is used when parsing the process PATH to search for external helper programs.
SHOW_PROGRESS If this is set to a non-empty value, then
pdfroff will always behave as if the
--report-progress option is specified, on the command line.
.
--------------------------------------------------------------------
.
Temporary files, created by
pdfroff , are placed in the directory specified by environment variables (see
section
ENVIRONMENT ), and named according to the convention
pdf $$ .*\c , where
$$ is the standard shell variable representing the process ID of the
pdfroff process itself, and
* represents any of a number of extensions used by
pdfroff for temporary and intermediate files.
.
--------------------------------------------------------------------
.
While
pdfroff imposes neither any restriction on, nor any requirement for,
the use of any specific
groff macro package, a number of supplied macro packages,
and in particular those associated with the package
pdfmark.tmac , are best suited for use with
pdfroff as the preferred formatter.
Detailed documentation on the use of these packages may be found,
in PDF format, in the reference guide
"\*(lqPortable Document Format Publishing with GNU Troff\*(rq" , included in the installed documentation set as
@PDFDOCDIR@/pdfmark.pdf . .
--------------------------------------------------------------------
.
This man page is distributed under the terms of the GNU Free Documentation License (FDL), version 1.1 or later, and is part of the GNU troff software package. It was originally written by Keith Marshall, .nohy <keith.d.marshall@ntlworld.com>, who also wrote the implementation of the pdfroff program, to which it relates.
You should have received a copy of the FDL as part of the
GNU troff distribution; it is also available on-line, at the GNU
.Q copyleft
site,
.nohy <http://www.gnu.org/copyleft/fdl.html>.
.
--------------------------------------------------------------------
EOF / vim: ft=groff