[groff] 03/08: [docs]: Revise trap documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c5ff7fd8724d5fcb764ca27789fc2ca7c1fd12d7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Nov 16 17:36:27 2020 +1100

    [docs]: Revise trap documentation.
    
    More carefully document behavior when request arguments are missing.
    
    Use "name" instead of "macro" for metasyntactic variable names since
    this name space includes strings, diversions, and boxes too.
    
    Recast for less jarring English grammar.  Rename from "leading spaces
    macro" to "leading space macro".  The mass noun has a better feel in
    prose; the subject under discussion encompasses both a discrete
    (\n[lsn]) and continuous (\n[lss]) quantity.
    
    Mark node/section "Traps" with "@codequote{undirected,backtick} on" as
    it has now been reviewed for glyph correctness.
    
    * doc/groff.texi (Breaking): Rename "leading spaces macro".
      (Traps): Mention leading space traps and the category of vertical
      position traps in introduction.  Note that macros called by traps do
      not receive arguments.  Coalesce 1-sentence paragraph into its
      predecessor.
    
      (Page Location Traps): Clarify that page location traps are sprung
      when reached or _passed_ in the _downward direction_ and that they
      also apply to _diversion traps_.  Move semantics of "dist" parameter
      here since the information applies to multiple requests.
    
      <.vpt>: Mark argument as optional; note that vertical position traps
      are enabled if it is absent.  Drop sentence observing that input line
      traps aren't vertical position traps; it is not unique in this
      respect (old language from before .blm and .lsm, maybe.).
    
      <.wh>: Summarize operation better with lead sentence.  Observe that
      .wh without a name argument removes (only) the first trap planted at
      the given location.
    
      Make example more realistic by using strings for title and date in
      header trap instead of literal "Title" and "Date".
    
      Discuss page location traps in terms of being "visible" rather than
      "active", since the analogical term "hide" is already used.
    
      Explicitly call out .ptr as useful to debug page location traps.  Add
      concept index nodes.
    
      <.ch>: Summarize operation better with lead sentence.
    
      Describe behavior of multiple traps at a given location more
      carefully; it is when a trap is _planted_ at a location that
      determines the active trap, whether this is done with .wh (which
      clobbers all existing traps at that location) or .ch.  Use the verb
      "planted" as already established in preference to "defined", because
      when a trap-invoked macro was _defined_ has no bearing on this.
    
      Update example to mark .ptr output as going to stderr instead of
      stdout.
    
      (BLank Line Traps): Use "name" instead of "macro" for metasyntactic
      variable name since the name space includes strings, diversions, and
      boxes too.  Move here documentation of the fact that lines with _only_
      "leading" spaces (that lead nothing but a newline) also qualify as
      "blank".
    
      (Input Line Traps) <.it>: Describe macro behavior more completely in
      lead sentence.  Be more precise about what doesn't count as a "text
      line".
    
      (Leading Space Traps): Rename in node, subsection, and content.
    
      Comment out extensive discussion of what a leading space macro "sees".
      I cannot make any sense of this.  As far as my experiments can reveal,
      lsm traps don't receive any arguments.  Just deleting this material
      would essentially revert 834c13a589bd40a30ef19e156301c92712a1552b, and
      I'm not brave enough to do that because it was written by Werner, who
      implemented .lsm.  Am I missing something?
    
      (End-of-input Traps) <.em>: Describe macro behavior more completely in
      lead sentence.  Document behavior when no parameter is present.
    
      Describe use case more fully and note its real-world application in
      the man(1) command.
    
      (Debugging) <.ptr>: Comment out statement that empty slots in the page
      location trap list can "affect the priority of subsequently planted
      traps".  After many experiments, I cannot see how they do.  Perhaps an
      expert can advise.
    
      (generally): Say "GNU troff" instead of "gtroff".  Stop prefixing
      lists and examples with sentence fragments.  Refer simply to
      "registers", not "number registers".  Prefer "count" over "number"
      when referring to discrete, non-dimensioned quantities stored in
      registers.  Use full English sentences when documenting default
      scaling indicators.  Editor annoyed!
    
    * man/groff.7.man:
    * man/groff_diff.7.man: Resynchronize with the foregoing.
---
 doc/groff.texi       | 277 ++++++++++++++++++++++++++++-----------------------
 man/groff.7.man      | 131 ++++++++++++++++--------
 man/groff_diff.7.man |  64 ++++++++----
 3 files changed, 286 insertions(+), 186 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index c06b185..b238722 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4582,11 +4582,11 @@ be modified with the blank line macro request 
@code{blm}.  @xref{Blank
 Line Traps}.  Macro packages may discourage or disable the blank line
 method of paragraphing in favor of their own macros.
 
-@cindex leading spaces macro (@code{lsm})
+@cindex leading space macro (@code{lsm})
 A line that begins with a space causes a break and the space is output
 at the beginning of the next line.  This space isn't @emph{adjusted}
 (see below); however, this behavior can be modified with the leading
-spaces macro request @code{lsm}.  @xref{Leading Spaces Traps}.  Again,
+spaces macro request @code{lsm}.  @xref{Leading Space Traps}.  Again,
 macro packages may provide other methods of producing indented
 paragraphs.
 
@@ -12811,15 +12811,19 @@ Instead, use the @code{eqn} preprocessor.
 
 @c =====================================================================
 
+@codequotebacktick on
+@codequoteundirected on
+
 @node Traps, Diversions, Drawing Requests, gtroff Reference
 @section Traps
 @cindex traps
 
 @dfn{Traps} are locations that, when reached, call a specified macro.
 These traps can occur at a given location on the page, at a given
-location in the current diversion, at a blank line, after a certain
-number of input lines, or at the end of input.
-
+location in the current diversion (together, these are known as
+@emph{vertical position traps}), at a blank line, at a line with
+leading space characters, after a certain number of input lines, or at
+the end of input.  Macros invoked by traps have no arguments.
 @cindex planting a trap
 @cindex trap, planting
 Setting a trap is also called @dfn{planting}.
@@ -12833,7 +12837,7 @@ executed.
 * Diversion Traps::
 * Input Line Traps::
 * Blank Line Traps::
-* Leading Spaces Traps::
+* Leading Space Traps::
 * End-of-input Traps::
 @end menu
 
@@ -12844,9 +12848,9 @@ executed.
 @cindex page location traps
 @cindex traps, page location
 
-@dfn{Page location traps} perform an action when @code{gtroff} reaches
-or passes a certain vertical location on the page.  Page location traps
-have a variety of purposes, including:
+@dfn{Page location traps} perform an action when GNU @code{troff}
+reaches or passes a certain vertical location on the page or in a
+diversion.  Page location traps have a variety of purposes.
 
 @itemize
 @item
@@ -12859,47 +12863,48 @@ setting body text in multiple columns
 setting footnotes
 @end itemize
 
-@DefreqList {vpt, flag}
+@noindent
+The location parameter used in page location traps has a default scaling
+indicator of @samp{v}, and its value is rounded to be multiples of the
+vertical resolution (as given in register @code{.V}).
+
+@DefreqList {vpt, [@Var{flag}]}
 @DefregListEndx {.vpt}
 @cindex enabling vertical position traps (@code{vpt})
 @cindex vertical position traps, enabling (@code{vpt})
 @cindex vertical position trap enable register (@code{.vpt})
-Enable vertical position traps if @var{flag} is non-zero, or disables
-them otherwise.  Vertical position traps are traps set by the @code{wh}
-request, or by @code{dt} within a diversion.  Traps set by the @code{it}
-request are not vertical position traps.  The parameter that controls
-whether vertical position traps are enabled is global.  Initially
-vertical position traps are enabled.  The current setting of this is
-available in the @code{.vpt} read-only number register.
+Enable vertical position traps if @var{flag} is non-zero or absent;
+disable them otherwise.  Vertical position traps are only those set by
+the @code{wh} request or by @code{dt} within a diversion.  The parameter
+that controls whether vertical position traps are enabled is global.
+Initially, vertical position traps are enabled.  The current setting of
+this is available in the @code{.vpt} read-only register.
 
 A page can't be ejected if @code{vpt} is set to zero.
 @endDefreq
 
-@Defreq {wh, dist [@Var{macro}]}
-Set a page location trap.  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.  Default scaling indicator is
-@samp{v}; values of @var{dist} are always rounded to be multiples of the
-vertical resolution (as given in register @code{.V}).
-
-@var{macro} is the name of the macro to execute when the trap is sprung.
-If @var{macro} is missing, remove the first trap (if any) at @var{dist}.
+@Defreq {wh, dist [@Var{name}]}
+Call macro @var{name} when the vertical position @var{dist} on the page
+is reached or passed in the downward direction.  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.
 
 @cindex page headers
 @cindex page footers
 @cindex headers
 @cindex footers
-The following is a simple example of how many macro packages set headers
-and footers.
+An example of how a macro package might set headers and footers follows.
 
 @Example
-.de hd                \" Page header
+.de hd                \" page header
 '  sp .5i
-.  tl 'Title''date'
+.  tl '\\*[Title]''\\*[Date]'
 '  sp .3i
 ..
 .
-.de fo                \" Page footer
+.de fo                \" page footer
 '  sp 1v
 .  tl ''%''
 '  bp
@@ -12909,29 +12914,34 @@ and footers.
 .wh -1i fo            \" trap one inch from bottom
 @endExample
 
-A trap at or below the bottom of the page is ignored; it can be made
-active by either moving it up or increasing the page length so that the
-trap is on the page.
+A trap at or below the bottom of the page is ignored becaue the vertical
+position never reaches it; it can be made visible by either moving it up
+or increasing the page length so that the trap is on the page.
 
 Negative trap values always use the @emph{current} page length; they are
-not converted to an absolute vertical position:
+not converted to an absolute vertical position.
+@cindex page position traps, debugging
+@cindex debugging page position traps
+We can use the @code{ptr} request to dump our page location traps to the
+standard error stream (@pxref{Debugging}).
 
 @Example
 .pl 5i
 .wh -1i xx
 .ptr
-    @result{} xx      -240
+    @error{} xx      -240
 .pl 100i
 .ptr
-    @result{} xx      -240
+    @error{} xx      -240
 @endExample
 
-It is possible to have more than one trap at the same location; to do
-so, the traps must be defined at different locations, then moved
-together with the @code{ch} request; otherwise the second trap would
-replace the first one.  Earlier defined traps hide later defined traps
-if moved to the same position (the many empty lines caused by the
-@code{bp} request are omitted in the following example):
+It is possible to have more than one trap at the same location (although
+only one at a time can be @emph{visible}); to achieve this, the traps
+must be defined at different locations, then moved to the same place
+with the @code{ch} request.  Only a @dfn{visible} page location trap
+will be invoked; a trap planted earlier at a location hides those moved
+there later as shown in the following example (the many empty lines
+caused by the @code{bp} request are omitted).
 
 @Example
 .de a
@@ -12966,27 +12976,27 @@ if moved to the same position (the many empty lines 
caused by the
 @Defreg {.t}
 @cindex distance to next trap register (@code{.t})
 @cindex trap, distance, register (@code{.t})
-A read-only number register holding the distance to the next trap.
+A read-only register holding the distance to the next trap.
 
 If there are no traps between the current position and the bottom of the
 page, it contains the distance to the page bottom.  In a diversion, the
 distance to the page bottom is infinite (the returned value is the
-biggest integer that can be represented in @code{groff}) if there are
-no diversion traps.
+largest integer that can be represented in @code{groff}) if there are no
+diversion traps.
 @endDefreg
 
-@Defreq {ch, macro [@Var{dist}]}
+@Defreq {ch, name [@Var{dist}]}
 @cindex changing trap location (@code{ch})
 @cindex trap, changing location (@code{ch})
-Change the location of a trap.  The first argument is the name of the
-macro to be invoked at the trap, and the second argument is the new
-location for the trap (note that the parameters are specified in
-opposite order as in the @code{wh} request).  This is useful for
-building up footnotes in a diversion to allow more space at the bottom
-of the page for them.
+Change the location of a trap by moving macro @var{name} to new location
+@var{dist}, or by unplanting it altogether if @var{dist} is absent.
+Parameters to @code{ch} are specified in the opposite order from
+@code{wh}.  If @var{name} is the earliest planted macro of multiple
+traps at the same location, (re)moving it from that location exposes the
+macro next most recently planted at the same place.
 
-Default scaling indicator for @var{dist} is @samp{v}.  If @var{dist} is
-missing, the trap is removed.
+Changing a trap's location is useful for building up footnotes in a
+diversion to allow more space at the bottom of the page for them.
 
 @c XXX
 
@@ -12998,10 +13008,10 @@ missing, the trap is removed.
 @endDefreq
 
 @Defreg {.ne}
-The read-only number register @code{.ne} contains the amount of space
-that was needed in the last @code{ne} request that caused a trap to be
-sprung.  Useful in conjunction with the @code{.trunc} register.
-@xref{Page Control}.
+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.
+Useful in conjunction with the @code{.trunc} register.  @xref{Page
+Control}.
 
 Since the @code{.ne} register is only set by traps it doesn't make much
 sense to use it outside of trap macros.
@@ -13068,20 +13078,19 @@ most cases, this is not the expected behaviour.
 @cindex diversion traps
 @cindex traps, diversion
 
-@Defreq {dt, [@Var{dist} @Var{macro}]}
+@Defreq {dt, [@Var{dist} @Var{name}]}
 @cindex @code{.t} register, and diversions
 @cindex setting diversion trap (@code{dt})
 @cindex diversion trap, setting (@code{dt})
 @cindex trap, diversion, setting (@code{dt})
-Set a trap @emph{within} a diversion.  @var{dist} is the location of the
-trap (as with the @code{wh} request, the default scaling indicator is
-@samp{v}) and @var{macro} is the name of the macro to be invoked.  If
-called with fewer than two arguments, the diversion trap is removed.
+Set a trap @emph{within} a diversion at location @var{dist}.  The
+location is interpreted relative to diversion rather than page
+boundaries.  If called with fewer than two arguments, the diversion trap
+is removed.
 
 There exists only a single diversion trap.
 
-The number register @code{.t} still works within diversions.
-@xref{Diversions}.
+The register @code{.t} works within diversions.  @xref{Diversions}.
 @endDefreq
 
 @c ---------------------------------------------------------------------
@@ -13091,16 +13100,16 @@ The number register @code{.t} still works within 
diversions.
 @cindex input line traps
 @cindex traps, input line
 
-@DefreqList {it, n macro}
-@DefreqListEndx {itc, n macro}
+@DefreqList {it, n name}
+@DefreqListEndx {itc, n name}
 @cindex setting input line trap (@code{it})
 @cindex input line trap, setting (@code{it})
 @cindex trap, input line, setting (@code{it})
-Set an input line trap.  @var{n}@tie{}is the number of lines of input
-that may be read before springing the trap, @var{macro} is the macro to
-be invoked.  Request lines are not counted as input lines.
+Set an input line trap, calling macro @var{name} after the next
+@var{n}@tie{}lines of text input have been read.  Lines beginning with
+the control character or no-break control character are not counted.
 
-For example, one possible use is to have a macro that prints the next
+One possible use of @code{it} is to have a macro that prints the next
 @var{n}@tie{}lines in a bold font.
 
 @Example
@@ -13118,80 +13127,87 @@ For example, one possible use is to have a macro that 
prints the next
 @cindex interrupted lines and input line traps (@code{itc})
 @cindex traps, input line, and interrupted lines (@code{itc})
 @cindex lines, interrupted, and input line traps (@code{itc})
-The @code{itc} request is identical except that an interrupted text line
-(ending with @code{\c}) is not counted as a separate line.
+As @code{it}, except that interrupted text lines (those ending with
+@code{\c}) are not counted as separate lines.
 
 Both requests are associated with the current environment
 (@pxref{Environments}); switching to another environment disables the
-current input trap, and going back reactivates it, restoring the number
+current input trap, and going back reactivates it, restoring the count
 of already processed lines.
 @endDefreq
 
 @c ---------------------------------------------------------------------
 
-@node Blank Line Traps, Leading Spaces Traps, Input Line Traps, Traps
+@node Blank Line Traps, Leading Space Traps, Input Line Traps, Traps
 @subsection Blank Line Traps
 @cindex blank line traps
 @cindex traps, blank line
 
-@Defreq {blm, [@Var{macro}]}
+@Defreq {blm, [@Var{name}]}
 @cindex blank line macro (@code{blm})
-Set a blank line trap.  If a blank line macro is thus defined, GNU
-@code{troff} executes @var{macro} when a blank line is encountered in
-the input file, instead of the usual behavior (@pxref{Breaking}).  If no
-argument is supplied, the default blank line behavior is (re-)asserted.
+Set a blank line trap, calling the macro @var{name} when GNU
+@code{troff} encounters a blank line in an input file, instead of the
+usual behavior (@pxref{Breaking}).  A line consisting only of spaces is
+also treated as blank and subject to this trap.  If no argument is
+supplied, the default blank line behavior is (re-)established.
 @endDefreq
 
 @c ---------------------------------------------------------------------
 
-@node Leading Spaces Traps, End-of-input Traps, Blank Line Traps, Traps
-@subsection Leading Spaces Traps
-@cindex leading spaces traps
-@cindex traps, leading spaces
+@node Leading Space Traps, End-of-input Traps, Blank Line Traps, Traps
+@subsection Leading Space Traps
+@cindex leading space traps
+@cindex traps, leading space
 
-@DefreqList {lsm, macro}
+@DefreqList {lsm, [@Var{name}]}
 @DefregItemx {lsn}
 @DefregListEndx {lss}
 @cindex leading spaces macro (@code{lsm})
-Set a leading spaces trap.  @code{gtroff} executes @var{macro} when it
-encounters leading spaces in an input line; the implicit line break
-that normally happens in this case is suppressed.  A line consisting
-of spaces only, however, is treated as an empty line, possibly subject
-to an empty line macro set with the @code{blm} request.
-
-Leading spaces are removed from the input line before calling the
-leading spaces macro.  The number of removed spaces is stored in
-register @code{lsn}; the horizontal space that would be emitted if
-there was no leading space macro is stored in register @code{lss}.
-Note that @code{lsn} and @code{lss} are available even if no leading
-space macro has been set.
-
-The first thing a leading space macro sees is a token.  However, some
-escapes like @code{\f} or @code{\m} are handled on the fly (see
-@ref{Gtroff Internals}, for a complete list) without creating a token
-at all.  Consider that a line starts with two spaces followed by
-@code{\fIfoo}.  While skipping the spaces @code{\fI} is handled too so
-that groff's current font is properly set to @samp{I}, but the leading
-space macro only sees @code{foo}, without the preceding @code{\fI}.
-If the macro should see the font escape you have to `protect' it with
-something that creates a token, for example with @code{\&\fIfoo}.
+Set a leading space trap, calling the macro @var{name} when GNU
+@code{troff} encounters leading spaces in an input line; the implicit
+line break that normally happens in this case is suppressed.  If no
+argument is supplied, the default leading space behavior is
+(re-)established (@pxref{Breaking}).
+
+The count of leading spaces on an input line is stored in register
+@code{lsn}, and the amount of corresponding horizontal motion in
+register @code{lss}, irrespective of whether a leading space trap is
+set.  When it is, the leading spaces are removed from the input line,
+and no motion is produced before calling @var{name}.
+
+@c XXX The following discussion does not seem to be correct; leading
+@c space traps don't "see" _any_ input tokens.  Nothing on the line is
+@c passed to it as arguments, and tokens after leading spaces are
+@c processed normally after the designated macro returns. XXX
+@c
+@c The first thing a leading space macro sees is a token.  However, some
+@c escapes, like @code{\f} and @code{\m}, are handled on the fly
+@c (@pxref{Gtroff Internals} for a complete list) without creating a
+@c token at all.  Consider a line that starts with two spaces followed
+@c by @samp{\fIfoo}.  After skipping the spaces, @samp{\fI} is handled
+@c as well such that @code{groff}'s current font is set to @code{I}, but
+@c the leading space macro sees only @samp{foo} without the preceding
+@c @samp{\fI}.  If the macro should see the font escape, you have to
+@c ``protect'' it with something that creates a token, like the
+@c non-printing input break; for example, @samp{\&\fIfoo}.
 @endDefreq
 
 @c ---------------------------------------------------------------------
 
-@node End-of-input Traps,  , Leading Spaces Traps, Traps
+@node End-of-input Traps,  , Leading Space Traps, Traps
 @subsection End-of-input Traps
 @cindex end-of-input traps
 @cindex traps, end-of-input
 
-@Defreq {em, macro}
+@Defreq {em, [@Var{name}]}
 @cindex setting end-of-input trap (@code{em})
 @cindex end-of-input trap, setting (@code{em})
 @cindex trap, end-of-input, setting (@code{em})
 @cindex end-of-input macro (@code{em})
 @cindex macro, end-of-input (@code{em})
-Set a trap at the end of input.  @var{macro} is executed after the last
-line of the input file has been processed.
+Set a trap at the end of input, calling macro @var{name} after the last
+line of the last input file has been processed.  If no argument is
+given, any existing end-of-input trap is removed.
 
 For example, if the document had to have a section at the bottom of the
 last page for someone to approve it, the @code{em} request could be
@@ -13263,12 +13279,15 @@ This specific feature affects only the first 
potential page break
 caused by the end macro; further page breaks emitted by the end
 macro are handled normally.
 
-Another possible use of the @code{em} request is to make @code{gtroff}
-emit a single large page instead of multiple pages.  For example, one
-may want to produce a long plain-text file for reading on-screen.  The
-idea is to set the page length at the beginning of the document to a
-very large value to hold all the text, and automatically adjust it to
-the exact height of the document after the text has been output.
+Another possible use of the @code{em} request is to make GNU
+@code{troff} emit a single large page instead of multiple pages.  For
+example, one may want to produce a long plain text file for reading
+in a terminal or emulator without page footers and headers interrupting
+the body of the document.@footnote{This is the default behavior of some
+@command{man} programs.}  The idea is to set the page length at the
+beginning of the document to a very large value to hold all the text,
+and automatically adjust it to the exact height of the document after
+the text has been output.
 
 @Example
 .de adjust-page-length
@@ -13291,6 +13310,9 @@ simple solution would be to append the above macro to 
the macro
 package's end-of-input macro using the @code{am} request.
 @endDefreq
 
+@codequotebacktick off
+@codequoteundirected off
+
 
 @c =====================================================================
 
@@ -14813,12 +14835,19 @@ to the standard error stream.
 @endDefreq
 
 @Defreq {ptr, }
-@cindex dumping traps (@code{ptr})
-@cindex traps, dumping (@code{ptr})
-Report the names and positions of all traps (not including input line
-traps and diversion traps) to the standard error stream.  Empty slots in
-the page trap list are printed as well, because they can affect the
-priority of subsequently planted traps.
+@cindex dumping page position traps (@code{ptr})
+@cindex listing page position traps (@code{ptr})
+@cindex traps, page position, dumping (@code{ptr})
+@cindex traps, page position, listing (@code{ptr})
+Report the names and positions of all page location traps to the
+standard error stream.  Empty slots in the list, where a trap has been
+planted but subsequently (re)moved, are printed as well.
+@c "because they can affect the priority of subsequently planted traps."
+@c XXX Is that right?  It's useful to print the empty slots, I think,
+@c but a trap planted in an "empty" slot with .wh will become active.
+@c The slot seems to act as an immobile dummy list head, but does not
+@c change the basic list semantics.  .wh plants a trap at the head of
+@c the trap list at a location, and .ch plants a trap at the tail.
 @endDefreq
 
 @Defreq {fl, }
diff --git a/man/groff.7.man b/man/groff.7.man
index 846c61b..f7a0b0e 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1332,16 +1332,19 @@ Embolden Special Font
 when current font is
 .IR font .
 .
+.
 .TPx
 .REQ .blm
 Unset blank line macro (trap).
 .
 Restore default handling of blank lines.
 .
+.
 .TPx
-.REQ .blm macro
-Set blank line trap to
-.IR macro .
+.REQ .blm name
+Set blank line macro (trap) to
+.IR name .
+.
 .
 .TPx
 .REQ .box
@@ -1429,13 +1432,17 @@ to characters
 .IR c2 ,
 and so on.
 .
+.
 .TPx
-.REQ .ch "trap N"
-Change
-.I trap
-location
-to
-.IR N .
+.REQ .ch "name N"
+Change location of page location trap by moving macro
+.I name
+to new location
+.IR N ,
+or by unplanting it altogether if
+.I N
+absent.
+.
 .
 .TPx
 .REQ .char "c anything"
@@ -1670,10 +1677,10 @@ Clear diversion trap.
 .
 .
 .TPx
-.REQ .dt "N trap"
+.REQ .dt "N name"
 Set diversion trap to
 macro
-.I trap
+.I name
 at position
 .I N
 (default scaling indicator\~\c
@@ -1705,11 +1712,13 @@ Else part for if-else (\c
 .request .ie )
 request.
 .
+.
 .TPx
-.REQ .em "macro"
-The
-.I macro
-is run after the end of input.
+.REQ .em name
+Invoke macro
+.I name
+after the end of input.
+.
 .
 .TPx
 .REQ .eo
@@ -2019,19 +2028,25 @@ Change indentation according to
 (default scaling indicator\~\c
 .scaleindicator m ).
 .
+.
 .TPx
-.REQ .it "N trap"
-Set an input-line count trap for the next
-.I N
-lines.
+.REQ .it "n name"
+Set an input line trap,
+calling macro
+.IR name ,
+after the next
+.IR n\~ lines
+lines of text input have been read.
+.
 .
 .TPx
-.REQ .itc "N trap"
-Same as
-.request .it
+.REQ .itc "n name"
+As
+.request .it ,
 but don't count lines interrupted with
 .esc c .
 .
+.
 .TPx
 .REQ .kern
 Enable pairwise kerning.
@@ -2105,14 +2120,19 @@ Set line length according to
 default scaling indicator\~\c
 .scaleindicator m ).
 .
+.
 .TPx
 .REQ .lsm
-Unset the leading spaces macro.
+Unset the leading space macro (trap).
+.
+Restore default handling of lines with leading spaces.
+.
 .
 .TPx
-.REQ .lsm "macro"
-Set the leading spaces macro to
-.IR macro .
+.REQ .lsm name
+Set the leading space macro (trap) to
+.IR name .
+.
 .
 .TPx
 .REQ .ls
@@ -2366,10 +2386,12 @@ This behaves like the
 request except that input comes from the standard output of
 .IR command .
 .
+.
 .TPx
 .REQ .ptr
-Print the names and positions of all traps (not including input line
-traps and diversion traps) on stderr.
+Report names and positions of all page location traps to the standard
+error stream.
+.
 .
 .TPx
 .REQ .pvs
@@ -2752,11 +2774,17 @@ input lines.
 Unformat space characters and tabs in
 .IR diversion ,
 preserving font information.
+.
+.
 .TPx
-.REQ .vpt "n"
-Enable vertical position traps if
-.I n
-is non-zero, disable them otherwise.
+.REQ .vpt
+Enable vertical position traps.
+.
+.
+.TPx
+.B .vpt 0
+Disable vertical position traps.
+.
 .
 .TPx
 .REQ .vs
@@ -2783,14 +2811,28 @@ Set warnings code to
 Set scaling indicator used in warnings to
 .IR si .
 .
+.
 .TPx
-.REQ .wh "N"
-Remove (first) trap at position
-.IR N .
+.REQ .wh N
+Remove active trap at vertical position
+.IR N ;
+a negative value is measured upward from page bottom.
+.
 .
 .TPx
-.REQ .wh "N trap"
-Set location trap; negative means from page bottom.
+.REQ .wh "N name"
+Plant trap,
+calling macro
+.I name
+when page location
+.I N
+is reached or passed;
+a negative value is measured upward from page bottom.
+.
+Any active trap already present at
+.I N
+is replaced.
+.
 .
 .TPx
 .REQ .while "cond anything"
@@ -4518,9 +4560,11 @@ of the current font.
 .REG .sty
 The current font style (string-valued).
 .
+.
 .TPx
 .REG .t
-Vertical distance to the next trap.
+Distance to the next vertical position trap.
+.
 .
 .TPx
 .REG .T
@@ -4566,10 +4610,12 @@ Current vertical line spacing.
 .REG .V
 Number of basic units per vertical unit of output device resolution.
 .
+.
 .TPx
 .REG .vpt
 1\~if vertical position traps are enabled, 0\~otherwise.
 .
+.
 .TPx
 .REG .w
 Width of previous glyph.
@@ -4667,14 +4713,17 @@ image (set by
 .REG ln
 Output line number.
 .
+.
 .TPx
 .REG lsn
-The number of leading spaces of an input line.
+The count of leading spaces on an input line.
+.
 .
 .TPx
 .REG lss
-The horizontal space corresponding to the leading spaces of an input
-line.
+The amount of horizontal space corresponding to the leading spaces
+on an input line.
+.
 .
 .TPx
 .REG minutes
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index e515a9d..c3df561 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1141,8 +1141,8 @@ option of
 .
 .TP
 .BR .blm\~ [\c
-.IR macro ]
-Set a blank line trap.
+.IR name ]
+Set a blank line macro (trap).
 .
 If a blank line macro is thus defined,
 .I groff
@@ -1151,8 +1151,11 @@ executes
 when a blank line is encountered in the input file,
 instead of the usual behavior.
 .
+A line consisting only of spaces is also treated as blank and subject to
+this trap.
+.
 If no argument is supplied,
-the default blank line behavior is (re-)asserted.
+the default blank line behavior is (re-)established.
 .
 .
 .TP
@@ -2444,13 +2447,14 @@ zero, emitting a warning of type \[lq]range\[rq].
 .
 .
 .TP
-.BI .itc\~ n\~macro
-Variant of
-.B .it
-for which a line interrupted with
+.BI .itc\~ n\~name
+As
+.BR .it ,
+but a line interrupted with
 .B \[rs]c
 is not counted as an input line.
 .
+.
 .TP
 .BI .kern\~ n
 If
@@ -2537,18 +2541,34 @@ read-only number register
 .B \[rs]n[.linetabs]
 is set to\~1 if in line-tabs mode, and 0 otherwise.
 .
+.
 .TP
-.BI .lsm\~ xx
-Set the leading spaces macro to
-.IR xx .
-If there are leading spaces in an input line, it is invoked instead of
-the usual troff behaviour; the leading spaces are removed.
-Registers
-.B \[rs]n[lsn]
-and
-.B \[rs]n[lss]
-hold the number of removed leading spaces and the corresponding
-horizontal space, respectively.
+.BR .lsm\~ [\c
+.IR name ]
+Set the leading space macro (trap) to
+.IR name .
+.
+If there are leading space characters on an input line,
+.I name
+is invoked in lieu of the usual
+.I roff
+behavior;
+the leading spaces are removed.
+.
+The count of leading spaces on an input line is stored in
+.BR \[rs]n[lsn] ,
+and the amount of corresponding horizontal motion in
+.BR \[rs]n[lss] ,
+irrespective of whether a leading space trap is set.
+.
+When it is,
+the leading spaces are removed from the input line,
+and no motion is produced before calling
+.IR name .
+.
+If no argument is supplied,
+the default leading space behavior is (re-)established.
+.
 .
 .TP
 .BI .mso\~ file
@@ -3926,15 +3946,17 @@ Initialized at start-up.
 .B \[rs]n[hp]
 The current horizontal position at input line.
 .
+.
 .TP
 .B \[rs]n[lsn]
 .TQ
 .B \[rs]n[lss]
-If there are leading spaces in an input line, these registers
-hold the number of leading spaces and the corresponding horizontal
-space,
+If there are leading spaces on an input line,
+these registers hold the count of leading spaces and the amount of
+corresponding horizontal motion,
 respectively.
 .
+.
 .TP
 .B \[rs]n[minutes]
 The number of minutes after the hour.