Commit: 651fc10b18c4932dc4939e8cf47fc2c59259df63 - groff-pdfmark (hg)

Reference Documentation: PDF Publishing with GNU Troff

Commit MetaInfo

• Revision: 651fc10b18c4932dc4939e8cf47fc2c59259df63 (tree)
• Zeit: 2022-02-27 23:19:43
• Autor: Keith Marshall <keith@user...>
• Commiter: Keith Marshall

Log Message

Add discussion of "ms" document structure.

* pdfmark.ms (Section 3.1.1): Add content.
(Section 4): Add cross-reference label, named...
(pdf-publishing): ...thus.

Ändern Zusammenfassung

• modified: pdfmark.ms

Diff

diff -r 5da678ba39a9 -r 651fc10b18c4 pdfmark.ms
--- a/pdfmark.ms	Sun Feb 27 11:07:02 2022 +0000
+++ b/pdfmark.ms	Sun Feb 27 14:19:43 2022 +0000
@@ -3919,6 +3919,115 @@
 are described below.
 .
 .NH 3
+.XN -S -- Document Structuring Considerations when using \F[C]ms\F[] Macros
+.LP
+Every published document
+.EM must
+incorporate,
+as a minimum,
+a document body;
+additionally,
+many documents may include
+.EM \%front\(hymatter ,
+which precedes the body,
+and
+.EM \%end\(hymatter ,
+which follows the body.
+Additionally,
+when publishing as a PDF document,
+it may be desired to incorporate a document outline,
+referring to chapter,
+or section headings,
+within the document body.
+.LP
+Conventionally,
+when a document is to include a
+.EM "table of contents" ,
+this should be placed at the end of the
+.EM \%front\(hymatter .
+.LP
+Traditional
+.CW AT&T
+implementations of
+.CW ms
+provide a number of macros to control \%front\(hymatter style,
+(of which only the \(lqreleased paper\(rq style,
+selected by use of the
+.CW RP
+macro,
+is supported by
+.CW groff
+.CW ms ),
+accompanied by several macros to specify \%front\(hymatter content,
+(also supported by
+.CW groff
+.CW ms ).
+Both traditional,
+and
+.CW groff
+.CW ms
+implementations also provide a small set of macros
+to facilitate compilation of a table of contents;
+they do not,
+however,
+offer any standard facilities for creation
+of a corresponding document outline.
+.LP
+Unfortunately,
+the traditional
+.CW ms
+method of compiling the table of contents
+results in it being printed at the end of the document,
+rather than in its normal position,
+at the end of the \%front\(hymatter.
+Traditionally,
+this unusual placement of the table of contents would be corrected,
+by manual collation,
+after printing;
+emulation of this mechanical collation technique presents a challenge,
+when the document is to be published in PDF format.
+.LP
+Taking up the challenge of collating the various document sections
+into the correct order,
+when producing any PDF document,
+will necessitate special consideration during the PDF publication process;
+this will be discussed in greater depth,
+in
+.rn PDFHREF.PREFIX XX
+.XR pdf-publishing .
+.rn XX PDFHREF.PREFIX
+To accommodate any specialized processing which may be required,
+.CW spdf.tmac
+provides:\(en
+.QS
+.sp -\n(PDu
+.IP \(bu
+Macros to isolate the
+.EM \%front\(hymatter ,
+(excluding the
+.EM "table of contents" ),
+from the body of the document.
+.IP \(bu
+Further macros to compile a table of contents,
+and a corresponding PDF document outline,
+deriving both from section headings,
+.XR xh-xn-macros ). (
+.IP \(bu
+A redefined implementation of the
+.CW TC
+macro,
+(to be invoked at the end of the document,
+as in traditional
+.CW ms
+usage);
+this isolates the table of contents
+from its preceding \%front\(hymatter (if any),
+and from the document body,
+to facilitate the collation process.
+.\"nr PD +0.1v
+.QE
+.
+.NH 3
 .XN -S -- \F[C]ms\F[] Section Headings in PDF Documents
 .LP
 Traditionally,
@@ -3951,7 +4060,7 @@
 .bp
 .
 .NH 1
-.XN The PDF Publishing Process
+.XN -N pdf-publishing -- The PDF Publishing Process
 .
 .NH 2
 .XN -N do-xref -- Resolving Cross References