gbranden pushed a commit to branch master
in repository groff.
commit 2f7b3638f2b4e23940c6318079705f59ce3ef941
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Mon Nov 9 23:52:27 2020 +1100
pdfroff(1): Break input lines consistently.
Break input lines after (prose) commas, semicolons, and colons, and set
multi-word parentheticals on their own input lines.
Also delete some unnecessary commas altogether.
---
contrib/pdfmark/pdfroff.1.man | 204 +++++++++++++++++++++++++++---------------
1 file changed, 134 insertions(+), 70 deletions(-)
diff --git a/contrib/pdfmark/pdfroff.1.man b/contrib/pdfmark/pdfroff.1.man
index 68be499..fa0c743 100644
--- a/contrib/pdfmark/pdfroff.1.man
+++ b/contrib/pdfmark/pdfroff.1.man
@@ -104,7 +104,8 @@ is a wrapper program for the GNU text processing system,
.
It transparently handles the mechanics of multiple pass
.I groff
-processing, when applied to suitably marked up
+processing,
+when applied to suitably marked up
.I groff
source files,
such that tables of contents and body text are formatted separately,
@@ -127,30 +128,40 @@ interpreter to produce a finished PDF document.
.
.P
.I pdfroff
-makes no assumptions about, and imposes no restrictions on, the use of
-any
+makes no assumptions about,
+and imposes no restrictions on,
+the use of any
.I groff
macro packages which the user may choose to employ,
in order to achieve a desired document format;
-however, it
+however,
+it
.I does
include specific built in support for the
.I pdfmark
-macro package, should the user choose to employ it.
+macro package,
+should the user choose to employ it.
.
-Specifically, if the
+Specifically,
+if the
.I pdfhref
-macro, defined in the
+macro,
+defined in the
.I pdfmark.tmac
-package, is used to define public reference marks, or dynamic links to
-such reference marks, then
+package,
+is used to define public reference marks,
+or dynamic links to such reference marks,
+then
.I pdfroff
performs as many preformatting
.I groff
-passes as required, up to a maximum limit of
+passes as required,
+up to a maximum limit of
.IR four ,
-in order to compile a document reference dictionary, to resolve
-references, and to expand the dynamically defined content of links.
+in order to compile a document reference dictionary,
+to resolve
+references,
+and to expand the dynamically defined content of links.
.
.
.\" ====================================================================
@@ -159,16 +170,23 @@ references, and to expand the dynamically defined content
of links.
.
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
+(i.e.,
+a single character option introduced by a single hyphen),
+and if that option expects an argument,
+then it
.I must
-be specified independently (i.e., it may
+be specified independently
+(i.e.,
+it may
.I not
be appended to any group of other single character short form options).
.
.
.P
-Long form option names (i.e., those introduced by a double hyphen) may
+Long form option names
+(i.e.,
+those introduced by a double hyphen)
+may
be abbreviated to their minimum length unambiguous initial substring.
.
.
@@ -179,12 +197,15 @@ usage closely mirrors that of
.I groff
itself.
.
-Indeed, with the exception of the
+Indeed,
+with the exception of the
.BR \-h ,
.BR \-v ,
and
.BI \-T \ dev
-short form options, and all long form options, which are parsed
+short form options,
+and all long form options,
+which are parsed
internally by
.IR pdfroff ,
all options and file name arguments specified on the command line are
@@ -194,7 +215,8 @@ to control the formatting of the PDF document.
.
Consequently,
.I pdfroff
-accepts all options and arguments, as specified in
+accepts all options and arguments,
+as specified in
.IR groff (@MAN1EXT@),
which may also be considered as the definitive reference for all
standard
@@ -207,14 +229,20 @@ options and argument usage.
.\" ====================================================================
.
.I pdfroff
-accepts all of the short form options (i.e., those introduced by a
-single hyphen), which are available with
+accepts all of the short form options
+(i.e.,
+those introduced by a
+single hyphen),
+which are available with
.I groff
itself.
.
-In most cases, these are simply passed transparently to
+In most cases,
+these are simply passed transparently to
.IR groff ;
-the following, however, are handled specially by
+the following,
+however,
+are handled specially by
.IR pdfroff .
.
.TP
@@ -225,16 +253,19 @@ see below.
.
.TP
.B \-i
-Process standard input, after all other specified input files.
+Process standard input,
+after all other specified input files.
.
This is passed transparently to
.IR groff ,
-but, if grouped with other options, it
+but,
+if grouped with other options,
+it
.I must
be the first in the group.
.
-Hiding it within a group breaks standard input processing, in the
-multiple pass
+Hiding it within a group breaks standard input processing,
+in the multiple pass
.I groff
processing context of
.IR pdfroff .
@@ -260,7 +291,8 @@ see below.
.P
See
.IR groff (@MAN1EXT@)
-for a description of all other short form options, which are
+for a description of all other short form options,
+which are
transparently passed through
.I pdfroff
to
@@ -268,8 +300,10 @@ to
.
.
.P
-All long form options (i.e., those introduced by a double hyphen) are
-interpreted locally by
+All long form options
+(i.e.,
+those introduced by a double hyphen)
+ are interpreted locally by
.IR pdfroff ;
they are
.I not
@@ -281,28 +315,32 @@ unless otherwise stated below.
.B \-\-help
Causes
.I pdfroff
-to display a summary of the its usage syntax, and supported options,
+to display a summary of the its usage syntax,
+and supported options,
and then exit.
.
.TP
.B \-\-emit\-ps
-Suppresses the final output conversion step, causing
+Suppresses the final output conversion step,
+causing
.I pdfroff
to emit PostScript output instead of PDF.
.
-This may be useful, to capture intermediate PostScript output, when
-using a specialised postprocessor, such as
+This may be useful to capture intermediate PostScript output when using
+a specialised postprocessor,
+such as
.I gpresent
for example,
in place of the default Ghostscript PDF writer.
.
.TP
.B \-\-keep\-temporary\-files
-Suppresses the deletion of temporary files, which normally occurs
+Suppresses the deletion of temporary files,
+which normally occurs
after
.I pdfroff
-has completed PDF document formatting; this may be useful, when
-debugging formatting problems.
+has completed PDF document formatting;
+this may be useful when debugging formatting problems.
.
.IP
See section \[lq]Files\[rq] below for a description of the temporary
@@ -313,10 +351,11 @@ files used by
.B \-\-no\-pdf\-output
May be used with the
.BI \%\-\-reference\-dictionary= name
-option (described below) to eliminate the overhead of PDF formatting,
-when running
+option
+(described below)
+to eliminate the overhead of PDF formatting when running
.I pdfroff
-to create a reference dictionary, for use in a different document.
+to create a reference dictionary for use in a different document.
.
.TP
.B \-\-no\-reference\-dictionary
@@ -356,7 +395,8 @@ to leave them in place.
.TP
.BI \-\-pdf\-output= name
Specifies the name to be used for the resultant PDF document;
-if unspecified, the PDF output is written to standard output.
+if unspecified,
+the PDF output is written to standard output.
A future version of
.I pdfroff
may use this option,
@@ -374,7 +414,8 @@ completes processing of the current document.
.
This option
.I must
-be specified, if it is desired to save the reference dictionary,
+be specified,
+if it is desired to save the reference dictionary,
for use in references placed in other PDF documents.
.
.TP
@@ -410,14 +451,16 @@ pass operation
.IR only ,
in order to display the associated
.I groff
-version information, before exiting.
+version information,
+before exiting.
.
.
.\" ====================================================================
.SH Environment
.\" ====================================================================
.
-The following environment variables may be set, and exported,
+The following environment variables may be set,
+and exported,
to modify the behaviour of
.IR pdfroff .
.
@@ -433,9 +476,11 @@ to the start of the finished PDF document,
when formatting with traditional macro packages,
which print them at the end.
.
-However, users should not normally need to specify
+However,
+users should not normally need to specify
.IR \%PDFROFF_COLLATE ,
-(and indeed, are not encouraged to do so). If unspecified,
+(and indeed,
+are not encouraged to do so). If unspecified,
.I pdfroff
uses
.IR sed (@MAN1EXT@)
@@ -500,7 +545,8 @@ is required.
As in the case of
.IR \%PDFROFF_COLLATE ,
.I \%PDFROFF_KILL_NULL_PAGES
-is ignored, if
+is ignored,
+if
.I pdfroff
is invoked with the
.B \%\-\-no\-kill\-null\-pages
@@ -542,18 +588,20 @@ If
.I \%GROFF_TMPDIR
is
.I not
-specified, then the variables
+specified,
+then the variables
.IR TMPDIR ,
.I TMP
and
.I TEMP
-are considered in turn, as possible temporary file repositories.
-If none of these are set, then temporary files are created
+are considered in turn as possible temporary file repositories.
+If none of these are set,
+then temporary files are created
in the current directory.
.
.TP
.I GROFF_GHOSTSCRIPT_INTERPRETER
-Specifies the program to be invoked, when
+Specifies the program to be invoked when
.I pdfroff
converts
.I groff
@@ -570,7 +618,8 @@ overriding any explicit setting specified in the
environment.
.
If
.I \%GROFF_GHOSTSCRIPT_INTERPRETER
-is not specified, then
+is not specified,
+then
.I pdfroff
searches the process
.IR PATH ,
@@ -582,7 +631,7 @@ aborts.
.
.TP
.I GROFF_AWK_INTERPRETER
-Specifies the program to be invoked, when
+Specifies the program to be invoked when
.I pdfroff
is extracting reference dictionary entries from a
.I groff
@@ -590,16 +639,24 @@ intermediate message stream.
.
If
.I \%GROFF_AWK_INTERPRETER
-is not specified, then
+is not specified,
+then
.I pdfroff
searches the process
.IR PATH ,
-looking for any of the preferred programs, \[oq]gawk\[cq],
-\[oq]mawk\[cq], \[oq]nawk\[cq], and \[oq]awk\[cq], in this order; if
-none of these are found,
-.I pdfroff
-issues a warning message, and continue processing;
-however, in this case, no reference dictionary is created.
+looking for any of the preferred programs,
+\[oq]gawk\[cq],
+\[oq]mawk\[cq],
+\[oq]nawk\[cq],
+and \[oq]awk\[cq],
+in that order;
+if none of these are found,
+.I pdfroff
+issues a warning message,
+and continue processing;
+however,
+in this case,
+no reference dictionary is created.
.
.TP
.I OSTYPE
@@ -629,11 +686,12 @@ to search for external helper programs.
.
.TP
.I SHOW_PROGRESS
-If this is set to a non-empty value, then
+If this is set to a non-empty value,
+then
.I pdfroff
always behaves as if the
.B \%\-\-report\-progress
-option is specified, on the command line.
+option is specified on the command line.
.
.
.\" ====================================================================
@@ -643,20 +701,23 @@ option is specified, on the command line.
Input and output files for
.I pdfroff
may be named according to any convention of the user's choice.
-Typically, input files may be named according to the choice of the
-principal formatting macro package, e.g.,
+Typically,
+input files may be named according to the choice of the principal
+normatting macro package,
+e.g.,
.RI file .ms
might be an input file for formatting using the
.I ms
macros
.RI ( s.tmac );
-normally, the final output file should be named
+normally,
+the final output file should be named
.RI file .pdf .
.
.
.P
-Temporary files, created by
-.IR pdfroff ,
+Temporary files created by
+.I pdfroff
are placed in the file system hierarchy,
in or below the directory specified by environment variables
(see section \[lq]Environment\[rq] above).
@@ -681,7 +742,8 @@ where
is the standard shell variable representing the process identifier of
the
.I pdfroff
-process itself, and
+process itself,
+and
.I *
represents any of the extensions used by
.I pdfroff
@@ -816,10 +878,12 @@ extended features.
.P
While
.I pdfroff
-imposes neither any restriction on, nor any requirement for,
+imposes neither any restriction on,
+nor any requirement for,
the use of any specific
.I groff
-macro package, a number of supplied macro packages,
+macro package,
+a number of supplied macro packages,
and in particular those associated with the package
.IR pdfmark.tmac ,
are best suited for use with
_______________________________________________
Groff-commit mailing list
Groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
