* pdfroff.sh (PDFWRITE): Local shell variable replaced...

	(PDFROFF_POSTPROCESSOR_COMMAND): by this new  environment variable...
	(GROFF_GHOSTSCRIPT_INTERPRETER): with this bound to it.
	(PDFROFF_COLLATE, PDFROFF_KILL_NULL_PAGES): New environment variables.
	(--no-kill-null-pages): New command line option; implement it, and...
	(--help): Add description for it.

	* pdfroff.man (PDFROFF_POSTPROCESSOR_COMMAND): Document it.
	(PDFROFF_COLLATE, PDFROFF_KILL_NULL_PAGES): Document them.
	(--no-kill-null-pages): Document it.

1 files changed, 132 insertions, 0 deletions

diff --git a/contrib/pdfmark/pdfroff.man b/contrib/pdfmark/pdfroff.man
index 8402ee75..8f7266dc 100644
--- a/contrib/pdfmark/pdfroff.man
+++ b/contrib/pdfmark/pdfroff.man
@@ -103,6 +103,7 @@ pdfroff \- create PDF documents using
 .opta W name
 .opt  -emit-ps
 .opt  -no-toc-relocation
+.opt  -no-kill-null-pages
 .opte -stylesheet name
 .optx -pdf-output name
 .optx -reference-dictionary name
@@ -344,6 +345,22 @@ and relocate it to the start of the PDF document,
 when processing any document which lacks an automatically
 generated table of contents.
 .TP
+.B \-\-no\-kill\-null\-pages
+While preparing for simulation of the manual collation step,
+which is traditionally required to relocate of a
+.I "table of contents
+to the start of a document,
+.B pdfroff
+will accumulate a number of empty page descriptions
+into the intermediate
+.I PostScript
+output stream.
+During the final collation step,
+these empty pages are normally discarded from the finished document;
+this option forces
+.B pdfroff
+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.
@@ -401,6 +418,113 @@ The following environment variables may be set, and exported,
 to modify the behaviour of
 .BR pdfroff .
 .TP
+.B PDFROFF_COLLATE
+Specifies the program to be used
+for collation of the finshed PDF document.
+.IP
+This collation step may be required to move
+.I tables of contents
+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
+.BR PDFROFF_COLLATE ,
+(and indeed,
+are not encouraged to do so).
+If unspecified,
+.B pdfroff
+will use
+.BI sed (@MAN1EXT@)
+by default,
+which will normally suffice.
+.IP
+If
+.B PDFROFF_COLLATE
+.I is
+specified,
+then it must act as a filter,
+accepting a list of file name arguments,
+and write its output to the
+.I stdout
+stream,
+whence it is piped to the
+.BR PDFROFF_POSTPROCESSOR_COMMAND ,
+to produce the finished PDF output.
+.IP
+When specifying
+.BR PDFROFF_COLLATE ,
+it will normally be necessary to also specify
+.BR PDFROFF_KILL_NULL_PAGES .
+.IP
+.B PDFROFF_COLLATE
+is ignored,
+if
+.B pdfroff
+is invoked with the
+.I \-\-no\-kill\-null\-pages
+option.
+.TP
+.B PDFROFF_KILL_NULL_PAGES
+Sepcifies options to be passed to the
+.B PDFROFF_COLLATE
+program.
+.IP
+It should not normally be necessary to specify
+.BR PDFROFF_KILL_NULL_PAGES .
+The internal default is a
+.BI sed (@MAN1EXT@)
+script,
+which is intended to remove completely blank pages
+from the collated output stream,
+and which should be appropriate in most applications of
+.BR pdfroff .
+However,
+if any alternative to
+.BI sed (@MAN1EXT@)
+is specified for
+.BR PDFROFF_COLLATE ,
+then it is likely that a corresponding alternative specification for
+.B PDFROFF_KILL_NULL_PAGES
+will be required.
+.IP
+As in the case of
+.BR PDFROFF_COLLATE ,
+.B PDFROFF_KILL_NULL_PAGES
+is ignored,
+if
+.B pdfroff
+is invoked with the
+.I \-\-no\-kill\-null\-pages
+option.
+.TP
+.B PDFROFF_POSTPROCESSOR_COMMAND
+Specifies the command to be used for the final document conversion
+from PostScript intermediate output to PDF.
+It must behave as a filter,
+writing its output to the
+.I stdout
+stream,
+and must accept an arbitrary number of
+.I files ...
+arguments,
+with the special case of
+.I \-
+representing the
+.I stdin
+stream.
+.IP
+If unspecified,
+.B PDFROFF_POSTPROCESSOR_COMMAND
+defaults to:
+.RS 2
+.IP
+.I
+.ad l
+.nohy gs \-dBATCH \-dQUIET \-dNOPAUSE \-sDEVICE=pdfwrite \-sOutputFile=\-
+.ad
+.RE
+.TP
 .B GROFF_TMPDIR
 Identifies the directory in which
 .B pdfroff
@@ -425,6 +549,14 @@ converts
 .B groff
 PostScript output to PDF.
 If
+.B PDFROFF_POSTPROCESSOR_COMMAND
+is specified,
+then the command name it specifies is
+.I implicitly
+assigned to
+.BR GROFF_GHOSTSCRIPT_INTERPRETER ,
+overriding any explicit setting specified in the environment.
+If
 .B GROFF_GHOSTSCRIPT_INTERPRETER
 is not specified, then
 .B pdfroff