提交: 852dc6c1c5eb2e7adf5507cd0498225f1ef2d2ee - groff-pdfmark (hg)

Reference Documentation: PDF Publishing with GNU Troff

Commit MetaInfo

• 修訂: 852dc6c1c5eb2e7adf5507cd0498225f1ef2d2ee (tree)
• 時間: 2022-03-30 21:05:29
• 作者: Keith Marshall <keith@user...>
• Commiter: Keith Marshall

Log Message

Avoid keeps for widow and orphan line control.

* pdfmark.ms (KS, KE): Avoid using these for widow and orphan line
control; in particular do not include any section heading within such
a construct, as it may result in incorrect page numbering within the
generated table of contents; instead, use "ne" requests, with...
(\n[PD]u): ...this form for paragraph distance references used
consistently, in preference to...
(\n(PDu): ...this.

Change Summary

• modified: pdfmark.ms

差異

diff -r a01868c021e5 -r 852dc6c1c5eb pdfmark.ms
--- a/pdfmark.ms	Tue Mar 29 20:12:08 2022 +0100
+++ b/pdfmark.ms	Wed Mar 30 13:05:29 2022 +0100
@@ -510,7 +510,7 @@
 to help identify appropriate markup examples for implementing PDF features,
 such as:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \(bu
 Selecting a default document view, which defines how the document will appear
 when opened in the reader application; for example, when this document is
@@ -535,7 +535,7 @@
 Adding annotations, in the form of \(lqsticky notes\(rq, at strategic
 points within the PDF document.
 .QE
-.sp -\n(PDu
+.sp -\n[PD]u
 .LP
 All of the techniques described have been tested on
 .EM both
@@ -1116,7 +1116,7 @@
 .CW PDFHREF.VIEW.LEADING ,
 which determine the effective view specification as follows:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \*[= PDFBOOKMARK.VIEW]
 Establishes the magnification at which the document will be viewed,
 at the location of the \(lqbookmark\(rq; by default, it is defined by
@@ -1260,7 +1260,7 @@
 'ne 5
 For example, the setting used in this document:
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .LD
 .fam C
 \&.\e" Initialize the outline view to show only three heading levels,
@@ -1268,9 +1268,9 @@
 \&.\e"
 \&.nr PDFOUTLINE.FOLDLEVEL 3
 .DE
-.sp -\n(PDu
+.sp -\n[PD]u
 .QE
-.sp -\n(PDu
+.sp -\n[PD]u
 .LP
 results in only the first three levels of headings being displayed
 in the document outline,
@@ -1463,7 +1463,7 @@
 which defines the specific reference operation to be performed,
 and may be selected from:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \*[= O]
 Add an entry to the document outline.
 This operation has been described earlier,
@@ -1599,7 +1599,7 @@
 .CW pdfhref
 macro, are:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \*[= -N\0 name > <]
 Allows the
 .CWI name > <
@@ -1690,9 +1690,9 @@
 .EM without
 this option, the link destination is assumed to be defined
 within the same document.
-.KS
-.sp -\n(PDu
+.
 .IP \*[= -P\0 \(dqprefix\(hytext\(dq > <]
+'ne 4v
 Specifies
 .CWI \(dqprefix\(hytext\(dq > \%<
 to be attached to the
@@ -1706,10 +1706,9 @@
 .CWB W \& \& \(rq \(lq
 .CW pdfhref
 operators.
-.KE
-.KS
-.sp -\n(PDu
+.
 .IP
+'ne 3v
 Typically, this option would be used to insert punctuation before
 the link \%\(lqhot\(hyspot\(rq.
 Thus, there is little reason for the inclusion of spaces in
@@ -1717,10 +1716,9 @@
 however, if such space is required, then the enclosing double quotes
 .EM must
 be specified, as indicated.
-.KE
-.KS
-.sp -\n(PDu
+.
 .IP \*[= -A\0 \(dqaffixed\(hytext\(dq > <]
+'ne 4v
 Specifies
 .CWI \(dqaffixed\(hytext\(dq > \%<
 to be attached to the
@@ -1734,10 +1732,9 @@
 .CWB W \& \& \(rq \(lq
 .CW pdfhref
 operators.
-.KE
-.KS
-.sp -\n(PDu
+.
 .IP
+'ne 3v
 Typically, this option would be used to insert punctuation after
 the link \%\(lqhot\(hyspot\(rq.
 Thus, there is little reason for the inclusion of spaces in
@@ -1745,7 +1742,7 @@
 however, if such space is required, then the enclosing double quotes
 .EM must
 be specified, as indicated.
-.KE
+.
 .IP \*[= -T\0 tag > <]
 When specified with the
 .CWB O \& \& \(rq \(lq
@@ -1820,7 +1817,7 @@
 if only for the entirely cosmetic benefit of visually separating
 the main argument list from the sequence of preceding options.
 .QE
-.sp -\n(PDu
+.sp -\n[PD]u
 .LP
 In addition to the
 .CW pdfhref
@@ -1841,7 +1838,7 @@
 .CWBI file > <
 option is not specified, are:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \*[= -DF\0 dos\(hyfile > <]
 Specifies the name of the file in which a link destination is defined,
 using the file naming semantics of the
@@ -2063,8 +2060,8 @@
 or to modify the default format for cross reference links,
 .XR set-format ). (
 .
-.KS
 .NH 4
+'ne 4v+\n[PD]u
 .XN -N pdfhref-view -- Associating a Document View with a Reference Mark
 .LP
 In the same manner as each document outline reference, defined by the
@@ -2079,7 +2076,6 @@
 with the
 .CWB M \& \& \(rq \(lq
 operator, requires an associated document view specification.
-.KE
 .LP
 The mechanism whereby a document view is associated with a reference mark
 is entirely analogous to that employed for outline references,
@@ -2092,7 +2088,7 @@
 'ne 2v
 Thus, the reference view is defined in terms of:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \*[= PDFHREF.VIEW]
 A string,
 establishing the position of the reference mark within the viewing window,
@@ -2128,7 +2124,7 @@
 when the reference is selected.
 .QE
 .LP
-.sp -\n(PDu
+.sp -\n[PD]u
 Just as the view associated with outline references may be changed,
 by redefining
 .CW PDFBOOKMARK.VIEW ,
@@ -2479,7 +2475,7 @@
 and sometimes also referred to as a Uniform Resource Locator,
 or \(lqURL\(rq).
 .LP
-'ne 7v+(u;2*\n(PD)
+'ne 7v+(u;2*\n[PD])
 Since the mechanism for creating a link to a URI differs somewhat
 from that for creating PDF references, the
 .CW pdfhref
@@ -2640,7 +2636,7 @@
 by default;
 it is controlled by a pair of strings:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \*[= PDFHREF.BORDER]
 This string comprises a \%space\(hyseparated triplet of numeric values,
 optionally followed by a further \%space\(hyseparated
@@ -2668,10 +2664,10 @@
 thus appearing to disable the use of borders
 for link visualization.
 This differs from the \*[Adobe] default,
+'ne 4v+(u;2*\n[PD])
 which represents a solid (visible) line,
 one pixel in width,
 and with rectangular corners;
-'ne 3v+(u;2*\n(PD)
 this \*[Adobe] default may be reinstated,
 by explicitly defining
 .RS
@@ -2767,7 +2763,7 @@
 is established by a further string assignment,
 viz.:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \*[= PDFHREF.TEXT.COLOUR]
 Specifies the text colour,
 for rendition of PDF reference links.
@@ -2852,7 +2848,7 @@
 .pdfhref L -D set-colour -P \(lq -A \(rq -- use of colour
 reference,
 in the initial paragraph of
-'ne 3u*\n[PD]u+4v
+'ne 4v+(u;3*\n[PD])
 .pdfhref L -D user-format -A , -- this section
 points to a destination named by mark up similar to:\(en
 .QP
@@ -2864,8 +2860,8 @@
 .QP
 .CW ".pdfhref L -D set-colour -- use of colour"
 .
-.KS
 .NH 4
+'ne 3v+(u;2*\n[PD])
 .XN -N auto-format -- Using Automatically Formatted Reference Text
 .LP
 When the text within a link \%\(lqhot\(hyspot\(rq is specified explicitly,
@@ -2879,8 +2875,7 @@
 --
 .CWI explicit-text > <
 .fam
-'ne 2v+\n(PDu
-.KE
+'ne 2v+\n[PD]u
 .LP
 as described in
 .pdfhref L -D user-format -A , -- the preceding section
@@ -3061,8 +3056,8 @@
 as explained in
 .pdfhref L -D custom-format -A . -- the following section
 .
-.KS
 .NH 4
+'ne 5v+(u;3*\n[PD])
 .XN -N custom-format -- Customizing Automatically Formatted Reference Text
 .LP
 \(lqAutomatically formatted\(rq reference text is interpolated,
@@ -3077,7 +3072,7 @@
 option,
 .EM "and either" \^:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \(bu
 no explicit reference text is specified,
 (in which case,
@@ -3091,7 +3086,7 @@
 option is specified,
 in conjunction with explicit reference text.
 .QE
-.KE
+.sp -\n[PD]u
 .LP
 In each of these cases,
 the reference text is derived,
@@ -3190,7 +3185,7 @@
 default formatting macro is used,
 formatting progresses as follows:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .nr ITEM 0 1
 .de ITEMIZE ITEMIZE
 .IP \s'-2.5p'\\n+[ITEM]\s'+2.5p'.
@@ -3293,6 +3288,7 @@
 and which defines the extent of,
 the link \%\(lqhot\(hyspot\(rq region.
 .QE
+.sp -\n[PD]u
 .LP
 From the foregoing,
 it may be deduced that reference text,
@@ -3316,7 +3312,7 @@
 Within the formatted text,
 the keyword/value pair interpolations appear
 in the order in which \(lqknown\(rq keywords are found,
-'ne 7v+\n(PDu
+'ne 7v+\n[PD]u
 while parsing the
 .CW PDFHREF.INFO
 record;
@@ -3724,7 +3720,7 @@
 the user should:\(en
 .QS
 .nr ITEM 0 1
-.sp -\n(PDu
+.sp -\n[PD]u
 .ITEMIZE
 Define a page transition macro, to provide whatever features may be required,
 when a page transition occurs \(em e.g.\& printing footnotes,
@@ -3732,11 +3728,13 @@
 This macro should end by setting the output position at the correct
 vertical page offset, where the printing of running text is to restart,
 following the page transition.
+.
 .ITEMIZE
 Plant a trap to invoke this macro, at the appropriate vertical position
 marking the end of normal running text on each page.
-.KS
+.
 .ITEMIZE
+'ne 4v+(u;2*\n[PD])
 Initialize the
 .CW pdfhref
 hook into this page transition trap, by invoking
@@ -3753,7 +3751,6 @@
 .CW pdfhref
 will correctly restart mapping of active link regions,
 at the start of each new page.
-.KE
 .RE
 .QE
 .LP
@@ -3829,7 +3826,7 @@
 .CW groff
 formatting process is allowed to complete.
 .LP
-'ne 4v+\n(PDu
+'ne 4v+\n[PD]u
 To allow the user to choose when cached
 .CW pdfmark
 data is to be flushed to the output stream, the
@@ -4116,7 +4113,7 @@
 .CW spdf.tmac
 provides:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP \(bu
 Macros to isolate the
 .EM \%front\(hymatter ,
@@ -4264,7 +4261,7 @@
 .CW spdf.tmac
 macros is specified as:\(en
 .DS I
-.sp -\n(PDu
+.sp -\n[PD]u
 .CWB .SH
 .CWB .XH \& \& \0\c
 .CWB -N \& [ \ \c
@@ -4276,7 +4273,7 @@
 .CW ...
 .DE
 .DS I
-.sp -\n(PDu
+.sp -\n[PD]u
 .CWB .NH \& \& \0\c
 .CWI outline-level > <
 .CWB .XN \& \& \0\c
@@ -4288,7 +4285,7 @@
 .CW ...
 .DE
 .LP
-.sp -\n(PDu
+.sp -\n[PD]u
 In either case,
 the
 .CWI heading-text >... < \&
@@ -4345,7 +4342,7 @@
 .FE
 are:\(en
 .QS
-.sp -\n(PDu
+.sp -\n[PD]u
 .IP "\f(CB-N\fP \FC<\fIname\fP>\F[]"
 Create a
 .CW pdfhref