Re: your mail

[G. Branden Robinson]

Hi, Doug!

At 2021-09-09T14:02:29-0400, Douglas McIlroy wrote:
> > On 9/8/21, Douglas McIlroy <douglas.mcilroy@dartmouth.edu> wrote:
> >> A confusing entry in man 7 groff:
> >>
> >>        .wh N trap
> >>                  Set condition trap; negative means from page bottom.
> >
> > Where are you seeing this?  The 1.22.4 version of the groff man page
> > says "Set location trap" here, and git says this wording has been in
> > place since at least 2000.
> 
> The man page footer reads
> Groff Version 1.22.3           10 February 2018

It sounds like your distribution, if you use one, might be out of date.
groff 1.22.4 was released in December 2018.

As Dave noted, I did a bit of work on trap documentation last year.
Here's how that part of groff(7) now reads.

       .wh N     Remove active trap at vertical position N;  a  negative
                 value is measured upward from page bottom.
       .wh N name
                 Plant  trap, calling macro name when page location N is
                 reached or passed; a negative value is measured  upward
                 from page bottom.  Any active trap already present at N
                 is replaced.

While I was at it, I added a "Traps" section to the page, which distills
material from our Texinfo manual.

Traps
       Traps  are  locations  in  the output, or conditions on the input
       that, when reached or fulfilled, cause a specified  macro  to  be
       called.   These  traps  can occur at a given location on the page
       (.wh,  .ch);  at  a  given  location  in  the  current  diversion
       (.dt)—together, these are known as vertical position traps, which
       can be disabled and re-enabled (.vpt); at a blank line (.blm); at
       a line with leading space characters (.lsm); after a certain num‐
       ber  of  input  lines  (.it, .itc); or at the end of input (.em).
       Macros called by traps have no arguments.  Setting a trap is also
       called planting.  It is also said that a trap is  sprung  if  the
       associated macro is called.

       Registers  associated with trap management include vertical posi‐
       tion trap enablement status (\n[.vpt]), distance to the next trap
       (\n[.t]), amount of needed (.ne-requested) space that caused  the
       most recent vertical position trap to be sprung (\n[.ne]), amount
       of needed space truncated from the amount requested (\n[.trunc]),
       page   ejection   status   (\n[.pe]),  and  leading  space  count
       (\n[.lsn]) with its corresponding amount of motion (\n[.lss]).

Regards,
Branden

signature.asc
Description: PGP signature