[groff] 02/26: [docs]: Update documentation of `ch` and `wh`.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 63014b9426b4353815e6eb53fb47cf7c07617b04
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Dec 15 14:23:38 2022 -0600

    [docs]: Update documentation of `ch` and `wh`.
    
    ...and `warnscale`.
    
    * (groff.texi) Disclose default scaling unit used by `wh` and `ch` in
      their descriptions, instead of earlier in the Texinfo subsection/node.
      Drop statement about vertical position traps being rounded to vertical
      motion quantum; this is true in general of measurements.
    
    * (groff.7.man) Synopsize 1- and 2-argument forms of `ch` separately, as
      is done for other requests in this page.  Document default scaling
      indicators of `ch` and `wh`.  Migrate terminology and metasyntactic
      variable name for `warnscale` request: "scaling indicator" -> "scaling
      unit".  Characterize over-planted traps as "hidden", not "removed", as
      discussion in our Texinfo manual makes clear.
---
 doc/groff.texi  | 33 +++++++++++++++------------------
 man/groff.7.man | 29 +++++++++++++++++++----------
 2 files changed, 34 insertions(+), 28 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index f7317009d..e66f93ff1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14235,11 +14235,6 @@ reaches or passes a certain vertical location on the 
output page or in a
 diversion.  Their applications include setting page headers and footers,
 body text in multiple columns, and footnotes.
 
-@noindent
-The location parameter used in vertical position traps has a default
-scaling unit of @samp{v}, and its value is rounded to a multiple of the
-vertical motion quantum (found in the register @code{.V}).
-
 @DefreqList {vpt, [@Var{flag}]}
 @DefregListEndx {.vpt}
 @cindex enabling vertical position traps (@code{vpt})
@@ -14269,11 +14264,12 @@ A page can't be ejected if @code{vpt} is set to zero.
 
 @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.
+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.
 
 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
@@ -14376,14 +14372,15 @@ the largest representable integer in basic 
units---effectively infinite.
 @cindex changing trap location (@code{ch})
 @cindex trap, changing location (@code{ch})
 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 least recently planted at the same place.@footnote{It may
-help to think of each trap location as maintaining a queue; @code{wh}
-operates on the head of the queue, and @code{ch} operates on its tail.
-Only the trap at the head of the queue is visible.}
+@var{dist}, or by unplanting it altogether if @var{dist} is absent.  The
+default scaling unit is @samp{v}.  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 least recently planted at the same
+place.@footnote{It may help to think of each trap location as
+maintaining a queue; @code{wh} operates on the head of the queue, and
+@code{ch} operates on its tail.  Only the trap at the head of the queue
+is visible.}
 
 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.
diff --git a/man/groff.7.man b/man/groff.7.man
index f9baa7fd6..5974d2c72 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2529,14 +2529,19 @@ and so on.
 .
 .
 .TPx
-.REQ .ch "name \fR[\fPN\fR]"
+.REQ .ch name
+Unplant page location trap
+.IR name .
+.
+.
+.TPx
+.REQ .ch "name N"
 Change a planted page location trap
 .I name
 by moving its location to
-.IR N ,
-or by unplanting it altogether if
 .I N
-is absent.
+(default scaling unit\~\c
+.scaleindicator v ).
 .
 .
 .TPx
@@ -4117,16 +4122,18 @@ see
 .
 .
 .TPx
-.REQ .warnscale "si"
-Set scaling indicator used in warnings to
-.IR si .
+.REQ .warnscale "su"
+Set scaling unit used in warnings to
+.IR su .
 .
 .
 .TPx
 .REQ .wh N
 Remove active trap at vertical position
 .IR N ;
-a negative value is measured upward from page bottom.
+a negative value is measured upward from page bottom
+(default scaling unit\~\c
+.scaleindicator v ).
 .
 .
 .TPx
@@ -4137,11 +4144,13 @@ calling macro
 when page location
 .I N
 is reached or passed;
-a negative value is measured upward from page bottom.
+a negative value is measured upward from page bottom
+(default scaling unit\~\c
+.scaleindicator v ).
 .
 Any active trap already present at
 .I N
-is replaced.
+is hidden.
 .
 .
 .TPx