[groff] 05/09: [docs]: Expand discussion of traps.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f32cae212cd9f2c9bed1af431d47ce5fefc6dc30
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun May 21 18:53:36 2023 -0500

    [docs]: Expand discussion of traps.
    
    * Add new subsubsection/node to our Texinfo manual (and subsection to
      groff(7)): "The Implicit Trap", prompted by discussion with Dave
      Kemper.
    * Add subsection "Page location traps" to groff(7).
    * Document more restrictions on page location trap placement; you can't
      replace or hide the implicit trap, and "-0" is interpreted as "0".
      (You also can't place a trap less than one vertical motion quantum
      above the implicit trap, but that seems more like an instance of a
      more general bug than a design feature; see Savannah #56499.)
    * Rewrite header and footer definition example.
    * Drop footnote about an aspect of trap behavior being Heirloom Doctools
      troff compatible; it's DWB 3.3 troff compatible, too, so can probably
      be generally assumed.
    * Coalesce some one-sentence pargraphs into adjacent ones.
    * Recast description of `.pe` register.
    * Rewrite `.pe` register usage example.
    * Tighten wording.
    
    Also adjust dead-tree pagination.
---
 doc/groff.texi  | 148 ++++++++++++++++++++++++++++++++++++--------------------
 man/groff.7.man |  88 ++++++++++++++++++++++++++++++++-
 2 files changed, 183 insertions(+), 53 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 0133c887b..b6c20f6c4 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14270,6 +14270,7 @@ Environments save us considerable effort.
 
 @c =====================================================================
 
+@need 1000
 @c BEGIN Keep (roughly) parallel with subsection "Traps" of groff(7).
 @node Traps, Diversions, Deferring Output, GNU troff Reference
 @section Traps
@@ -14328,12 +14329,13 @@ A page can't be ejected if @code{vpt} is set to zero.
 
 @menu
 * Page Location Traps::
+* The Implicit Trap::
 * Diversion Traps::
 @end menu
 
 @c ---------------------------------------------------------------------
 
-@node Page Location Traps, Diversion Traps, Vertical Position Traps, Vertical 
Position Traps
+@node Page Location Traps, The Implicit Trap, Vertical Position Traps, 
Vertical Position Traps
 @subsubsection Page Location Traps
 @cindex page location traps
 @cindex traps, page location
@@ -14343,9 +14345,12 @@ Call macro @var{name} when the vertical position 
@var{dist} on the page
 is reached or passed in the downward direction.  The default scaling
 unit is @samp{v}.  Non-negative values for @var{dist} set the trap
 relative to the top of the page; negative values set the trap relative
-to the bottom of the page.  An existing @emph{visible} trap (see below)
-at @var{dist} is removed; this is @code{wh}'s sole function if
-@var{name} is missing.
+to the bottom of the page.  It is not possible to plant a trap less than
+one basic unit from the page bottom: a @var{dist} of @code{-0} is
+interpreted as @code{0}, the top of the page.@footnote{@xref{The
+Implicit Trap}.} An existing @emph{visible} trap (see below) at
+@var{dist} is removed; this is @code{wh}'s sole function if @var{name}
+is missing.
 
 A trap is sprung only if it is @dfn{visible}, meaning that its location
 is reachable on the page@footnote{A trap planted at @samp{20i} or
@@ -14353,27 +14358,45 @@ is reachable on the page@footnote{A trap planted at 
@samp{20i} or
 is not hidden by another trap at the same location already planted
 there.
 
+@need 1000
 @cindex page headers
 @cindex page footers
 @cindex headers
 @cindex footers
-An example of how a macro package might set headers and footers follows.
+A macro package might set headers and footers as follows; this example
+configures vertical margins of one inch to the body text, and one
+half-inch to the titles.  Observe the use of the no-break control
+character with @code{sp} request to position our text baselines,
+and the page number character @samp{%} used with the @code{tl} request.
 
 @Example
-.de hd                \" page header
+.\" hdfo.roff
+.de hd                  \" page header
+'  sp .5i
+'  tl '\\*(Ti''\\*(Da'  \" title and date strings
 '  sp .5i
-.  tl '\\*[Title]''\\*[Date]'
-'  sp .3i
 ..
-.
-.de fo                \" page footer
-'  sp 1v
+.de fo                  \" page footer
+'  sp .5i
 .  tl ''%''
-'  bp
+.  bp
 ..
-.
-.wh 0   hd            \" trap at top of the page
-.wh -1i fo            \" trap one inch from bottom
+.wh 0   hd             \" trap at top of the page
+.wh -1i fo             \" trap 1 inch from bottom
+@endExample
+
+To use these traps, copy the above (or load it from a file with the
+@code{so} or @code{mso} requests), then set up the strings it uses.
+
+@Example
+.so hdfo.roff
+.ds Ti Final Report\"
+.ds Da 21 May 2023\"
+.ti
+On 5 August of last year,
+this committe tasked me with the investigation of the
+CFIT (controlled flight into terrain) incident of
+.\" @i{...and so on...}
 @endExample
 
 A trap above the top or at or below the bottom of the page can be made
@@ -14385,8 +14408,7 @@ vertical position.
 @cindex debugging page location traps
 We can use the @code{ptr} request to dump our page location traps to the
 standard error stream (@pxref{Debugging}).  Their positions are reported
-in basic units appropriate to the device; an @code{nroff} device example
-follows.
+in basic units; an @code{nroff} device example follows.
 
 @Example
 .pl 5i
@@ -14473,9 +14495,8 @@ diversion to allow more space at the bottom of the page 
for them.
 The same macro can be installed simultaneously at multiple locations;
 however, only the earliest-planted instance---that has not yet been
 deleted with @code{wh}---will be moved by @code{ch}.  The following
-example (using an @code{nroff} device) illustrates this
-behavior.@footnote{@dots{}which is compatible with Heirloom Doctools
-@code{troff}.}  Blank lines have been elided from the output.
+example (using an @code{nroff} device) illustrates this behavior.  Blank
+lines have been elided from the output.
 
 @Example
 .de T
@@ -14518,10 +14539,8 @@ qux
 The read-only register @code{.ne} contains the amount of space that was
 needed in the last @code{ne} request that caused a trap to be sprung;
 it is useful in conjunction with the @code{.trunc} register.  @xref{Page
-Control}.
-
-Since the @code{.ne} register is set only by traps, it doesn't make
-sense to interpolate it outside of macros called by traps.
+Control}.  Since the @code{.ne} register is set only by traps, it
+doesn't make sense to interpolate it outside of macros called by traps.
 @endDefreg
 
 @Defreg {.trunc}
@@ -14534,7 +14553,6 @@ minus the amount of vertical motion produced by the 
@code{ne}
 request.  In other words, at the point a trap is sprung, it
 represents the difference of what the vertical position would have
 been but for the trap, and what the vertical position actually is.
-
 Since the @code{.trunc} register is set only by traps, it doesn't make
 sense to interpolate it outside of macros called by traps.
 @endDefreg
@@ -14543,45 +14561,71 @@ sense to interpolate it outside of macros called by 
traps.
 @cindex @code{bp} request, and traps (@code{.pe})
 @cindex traps, sprung by @code{bp} request (@code{.pe})
 @cindex page ejecting register (@code{.pe})
-A read-only register containing@tie{}1 while a page is being ejected
-with the @code{bp} request (or by the end of input), and
-0@tie{}otherwise.
+This Boolean-valued, read-only register interpolates@tie{}1 while a page
+is being ejected, and 0@tie{}otherwise.
 
-In the following example, only the second call to@tie{}@code{x} is
-caused by @code{bp}.
+In the following example, we plant the same trap at the top and the
+bottom of the page.  We also make the trap report its name and the
+vertical drawing position.
 
 @Example
-.de x
-\&.pe=\\n[.pe]
-.br
+.de T
+.tm \\$0: page \\n%, nl=\\n[nl] .pe=\\n[.pe]
 ..
-.wh 1v x
-.wh 4v x
-A line.
-.br
-Another line.
-.br
-    @result{} A line.
-       .pe=0
-       Another line.
-
-       .pe=1
+.ll 46n
+.wh 0 T
+.wh -1v T
+Those who can make you believe absurdities can make you
+commit atrocities. \[em] Voltaire
+    @error{} T: page 1, nl=0 .pe=0
+    @error{} T: page 1, nl=2600 .pe=1
+    @result{} Those who can make you believe absurdities can
+    @result{} make you commit atrocities. -- Voltaire
 @endExample
 @endDefreg
 
 @cindex diversions, and traps
 @cindex traps, and diversions
-An important fact to consider while designing macros is that diversions
-and traps do not interact normally.  For example, if a trap calls a
-header macro (while outputting a diversion) that tries to change the
-font on the current page, the effect is not visible before the diversion
-has completely been printed (except for input protected with @code{\!}
-or @code{\?}) since the data in the diversion is already formatted.  In
-most cases, this is not the expected behaviour.
+When designing macros, keep in mind that diversions and traps do
+normally interact.  For example, if a trap calls a header macro (while
+outputting a diversion) that tries to change the font on the current
+page, the effect is not visible before the diversion has completely been
+printed (except for input protected with @code{\!} or @code{\?}) since
+the data in the diversion is already formatted.  In most cases, this is
+not the expected behaviour.
+
+@c ---------------------------------------------------------------------
+
+@c BEGIN Keep (roughly) parallel with subsection "The implicit trap" of
+@c groff(7).
+@node The Implicit Trap, Diversion Traps, Page Location Traps, Vertical 
Position Traps
+@subsubsection The Implicit Trap
+@cindex implicit trap
+@cindex trap, implicit
+
+If, after starting @code{troff} without loading a macro package, you use
+the @code{ptr} request to dump a list of the active traps to the
+standard error stream,@footnote{@xref{Debugging}.}  nothing is reported.
+Yet the @code{.t} register will report a steadily decreasing value with
+every output line your document produces, and once the value of
+@code{.t} gets to within @code{.V} of zero, you will notice that
+something trap-like happens---the page is ejected, a new one begins, and
+the value of @code{.t} becomes large once more.
+
+This @dfn{implicit page trap} always exists in the top-level
+diversion;@footnote{@xref{Diversions}.} it works like a trap in some
+ways but not others.  Its purpose is to eject the current page and start
+the next one.  It has no name, so it cannot be moved or deleted with
+@code{wh} or @code{ch} requests.  You cannot hide it by placing another
+trap at its location, and can move it only by redefining the page length
+with @code{pl}.  Its operation is suppressed when vertical page traps
+are disabled with GNU @code{troff}'s @code{vpt} request.
+@c END Keep (roughly) parallel with subsection "The implicit trap" of
+@c groff(7).
 
 @c ---------------------------------------------------------------------
 
-@node Diversion Traps, Input Line Traps, Page Location Traps, Vertical 
Position Traps
+@node Diversion Traps, Input Line Traps, The Implicit Trap, Vertical Position 
Traps
 @subsubsection Diversion Traps
 @cindex diversion traps
 @cindex traps, diversion
diff --git a/man/groff.7.man b/man/groff.7.man
index 139516c65..8887464f6 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -6766,6 +6766,92 @@ with its corresponding amount of motion
 .
 .
 .\" ====================================================================
+.SS "Page location traps"
+.\" ====================================================================
+.
+A
+.I page location trap
+is called when the vertical drawing position reaches or passes the place
+at which it is planted
+(with
+.B .wh
+or
+.BR .ch ).
+.
+Non-negative page locations given to these requests set the trap
+relative to the top of the page;
+negative values set the trap relative to the bottom of the page.
+.
+It is not possible to plant a trap less than one basic unit from the
+page bottom:
+a location of \[lq]\-0\[rq] is interpreted as \[lq]0\[rq],
+the top of the page.
+.
+An existing
+.I visible
+trap
+(see below)
+at the same location is removed;
+this is
+.BR .wh 's
+sole function if its second argument is missing.
+.
+.
+.P
+A trap is sprung only if it is
+.I visible,
+meaning that its location is reachable on the page and it is not hidden
+by another trap at the same location already planted there.
+.
+(A trap planted at \[lq]20i\[rq] or \[lq]\-30i\[rq] will not be sprung
+on a page of length \[lq]11i\[rq].)
+.
+.
+.P
+A trap above the top or at or below the bottom of the page can be made
+visible by either moving it into the page area or increasing the page
+length so that the trap is on the page.
+.
+Negative trap values always use the
+.I current
+page length;
+they are not converted to an absolute vertical position.
+.
+Use
+.B .ptr
+to dump page location traps to the standard error stream;
+their positions are reported in basic units.
+.
+.
+.\" ====================================================================
+.SS "The implicit trap"
+.\" ====================================================================
+.
+An
+.I implicit page trap
+always exists in the top-level diversion;
+it works like a trap in some ways but not others.
+.
+Its purpose is to eject the current page and start the next one.
+.
+It has no name,
+so it cannot be moved or deleted with
+.B wh
+or
+.B ch
+requests.
+.
+You cannot hide it by placing another trap at its location,
+and can move it only by redefining the page length with
+.BR .pl .
+.
+Its operation is suppressed when vertical page traps are disabled with
+the
+.B vpt
+request.
+.
+.
+.\" ====================================================================
 .SH Diversions
 .\" ====================================================================
 .
@@ -7352,7 +7438,7 @@ You can browse it interactively with \[lq]info groff\[rq].
 .
 .
 .br
-.ne 2v
+.ne 4v
 .P
 \[lq]Troff User's Manual\[rq]
 by Joseph F.\& Ossanna,