[groff] 03/17: [docs]: Tweak page location trap explanation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 180766474d30d0400e7128c41d94439b1bc418b1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jun 6 13:25:55 2023 -0500

    [docs]: Tweak page location trap explanation.
---
 doc/groff.texi  | 19 +++++++++++--------
 man/groff.7.man | 32 +++++++++++++++++---------------
 2 files changed, 28 insertions(+), 23 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index a1a19e5e4..178105ca0 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14364,15 +14364,18 @@ A page can't be ejected if @code{vpt} is set to zero.
 @cindex page location traps
 @cindex traps, page location
 
+A @dfn{page location trap} is sprung when the vertical drawing position
+reaches or passes, in the downward direction, the place at which it is
+planted.
+
 @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.  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.  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 Page Trap}.} An existing @emph{visible} trap (see below) at
+Plant macro @var{name} as page location trap at @var{dist}.  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.  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 Page 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.
 
diff --git a/man/groff.7.man b/man/groff.7.man
index 58a98b0dc..c2daacf09 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2672,11 +2672,13 @@ Unplant page location trap
 .
 .
 .TPx
-.REQ .ch "name vertical-position"
-Change a planted page location trap
+.REQ .ch "name vpos"
+Change page location trap
 .I name
+planted by
+.request .wh
 by moving its location to
-.I vertical-position
+.I vpos
 (default scaling unit\~\c
 .scaleindicator v ).
 .
@@ -4442,23 +4444,22 @@ default:
 .
 .
 .TPx
-.REQ .wh vertical-position
-Remove active trap at
-.I vertical-position
+.REQ .wh vpos
+Remove visible page location trap at
+.I vpos
 (default scaling unit\~\c
 .scaleindicator v ).
 .
 .
 .TPx
-.REQ .wh "vertical-position name"
-Plant trap,
-calling macro
+.REQ .wh "vpos name"
+Plant macro
 .I name
-when page location
-.I vertical-position
-is reached or passed
+as page location trap at
+.I vpos
 (default scaling unit\~\c
-.scaleindicator v ).
+.scaleindicator v ),
+removing any visible trap already there.
 .
 .
 .TPx
@@ -6999,8 +7000,9 @@ with its corresponding amount of motion
 .
 A
 .I page location trap
-is called when the vertical drawing position reaches or passes the place
-at which it is planted
+is sprung when the vertical drawing position reaches or passes,
+in the downward direction,
+the place at which it is planted
 (with
 .B .wh
 or