コミット: e508edf7e839fc34c4790a0137a648341ba64d16 - groff-pdfmark (hg)

Reference Documentation: PDF Publishing with GNU Troff

コミットメタ情報

• リビジョン: e508edf7e839fc34c4790a0137a648341ba64d16 (tree)
• 日時: 2023-05-14 00:27:28
• 作者: Keith Marshall <keith@user...>
• コミッター: Keith Marshall

ログメッセージ

Describe method of finished document assembly.

* pdfmark.ms (Section 4.1.7): Add content.
(Section 4.1.4): Omit "$" prompt from "pdfroff" command example,
to maintain consistency with all earlier, and new examples.

変更サマリ

• modified: pdfmark.ms

差分

diff -r 4e3466df3691 -r e508edf7e839 pdfmark.ms
--- a/pdfmark.ms	Tue May 09 13:10:17 2023 +0100
+++ b/pdfmark.ms	Sat May 13 16:27:28 2023 +0100
@@ -6862,7 +6862,7 @@
 in the form:
 .DS I
 .CW
-$ pdfroff -mspdf --stylesheet=cover.ms pdfmark.ms > pdfmark.pdf
+pdfroff -mspdf --stylesheet=cover.ms pdfmark.ms > pdfmark.pdf
 .DE
 This causes
 .CW pdfroff
@@ -7884,6 +7884,189 @@
 .
 .NH 3
 .XN -S -N document-assembly -- How \F[C]pdfroff\F[] Assembles a Finished Document
+.LP
+After
+.CW pdfroff
+has completed each of the processing phases,
+enumerated as phase\~no.\|1 to phase\~no.\|5 in
+.XR-NO-PREFIX pdfroff-operation ,
+.EM "at least one" ,
+and
+.EM "at most three"
+intermediate \*[PostScript] output files will have been created,
+(in addition to the temporary files designated by the
+.CW WRKFILE ,
+.CW REFFILE ,
+and
+.CW REFCOPY
+shell variables).
+If only one intermediate output file is created, it
+.EM must
+be the document body component;
+if more than one such file is created, one
+.EM must
+be the document body component,
+while any others may be
+.EM "either one"
+of, or
+.EM both
+of a \%front\(hymatter component,
+and a table of contents component.
+In this final phase of
+.CW pdfroff
+processing,
+the entire complement of created intermediate output files is conjoined,
+in the order:
+.QS
+.sp -\n[PD]u
+.IP \(bu 2n
+\%Front\(hymatter component (if present);
+.IP \(bu
+Table of contents component (if present);
+.IP \(bu
+Document body component
+.QE
+to assemble the finished output document,
+either merging all component content into a single \*[PostScript] document,
+(if the
+.CW \%\-\-emit\-ps
+option has been specified),
+or normally,
+merging all content,
+and simultaneously converting to PDF.
+.
+.LP
+Depending on the particular complement
+of intermediate output files which have been created,
+document assembly proceeds as follows:
+.QS
+.sp -\n[PD]u
+.IP \(bu 2n
+If a \%front\(hymatter intermediate output file has been created,
+its content is simply copied, without change,
+to the beginning of the final output file.
+.
+.IP \(bu
+As has been noted previously, in
+.XR-NO-PREFIX toc-generation ,
+if a table of contents intermediate output file has been created,
+it
+.EM will
+contain the formatted table of contents,
+but this will be preceded by a sequence of blank pages,
+with one blank page for each page in the document body;
+these blank pages will (usually) not be wanted in the finished document,
+so, before merging this intermediate file content,
+it is passed through a
+.CW sed
+filter,
+to remove them;
+the residual comtent is then copied into the final output file,
+either following the \%front\(hymatter, if present,
+or otherwise, at its beginning.
+.
+.IP \(bu
+Finally,
+the content of the document body is read
+from its respective intermediate output file,
+and merged into the final output file,
+following any content which had previously been merged
+from \%front\(hymatter and table of contents intermediate output files;
+as in the case of table of contents intermediate output,
+this document body output is also passed, by default,
+through the same blank page removal
+.CW sed
+filter.
+.QE
+It may be observed that,
+by default,
+.CW pdfroff
+will filter
+.EM both
+the table of contents intermediate output, if any,
+and the document body intermediate output,
+to remove blank pages.
+While the intent of this is to discard
+.EM phantom
+blank pages,
+which precede the actual table of contents,
+and which follow the document body,
+it must be understood that it will actually remove
+.EM all
+blank pages\*[em]\c
+.EM both
+those which promote this intent,
+.EM and
+any others which may appear
+.EM within
+the table of contents,
+and the document body.
+This may, or may not, be desireable behaviour\*[em]it probably
+.EM is ,
+within the table of contents,
+but is less so within the document body,
+especially if the trailing blank pages,
+resulting from \%\(lqpen\(hyup\(rq formatting
+of an appended table of contents,
+have been optimized out,
+as suggested in
+.XR-NO-PREFIX body-formatting .
+.
+.LP
+Some control of blank page removal
+may be achieved by specification of the
+.CW \%\-\-no\-kill\-null\-pages
+option\*[em]or
+.CW \%\-\-no\-kill\-null\-pages[=< \c
+.CWI whence >] \& ,
+from the
+.CW \%groff-pdfmark-20230406.1
+release onwards\*[em]on the
+.CW pdfroff
+command line, or alternatively,
+and once again, only from the release of
+.CW \%groff-pdfmark-20230406.1
+onwards,
+by use of the
+.CW \%preserve_blank_pages=< \c
+.CWI whence >
+\%in\(hydocument hint.
+When supported, the
+.CWI whence > <
+argument may take a value of
+.CW toc \(rq, \(lq
+.CW body \(rq, \(lq
+or
+.CW all \(rq, \(lq
+with
+.CW all \(rq \(lq
+being the default,
+and equivalent to the original behaviour;
+its effect is to suppress removal of
+.EM all
+blank pages originating from the
+table of contents intermediate output file,
+.EM and
+from the document body intermediate output,
+which is probably not the desired effect.
+More useful behaviour may be to retain the default
+removal of blank pages originating from
+the table of contents intermediate output,
+while suppressing it for those originating within the document body;
+this may be achieved by invoking
+.CW pdfroff
+with a command such as:
+.QS
+.CW "pdfroff --no-kill-blank-pages=body ..."
+.QE
+or by including the equivalent \%in\(hydocument hint:
+.QS
+.CW ".pdfroff option preserve_blank_pages=body"
+.QE
+within the document source file,
+(perhaps making it conditional on some appropriate condition,
+such as selection of a duplex printing configuration,
+for example).
 .
 .NH 2
 .XN -N do-xref -- Further Considerations for Using Document References