mirror/groff
1
0
Fork 0
mirror of https://https.git.savannah.gnu.org/git/groff.git synced 2026-01-27 01:44:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

[docs]: Clarify vertical position trap material.

Browse Source 
* Move sentence about how these are sprung to correctly generalize.
* Emphasize contrast between page location traps (many per page) and
  diversion traps (one per diversion).
This commit is contained in:
G. Branden Robinson 2023-06-24 17:31:18 -05:00
parent 935803f501
commit ad0a8212df
2 changed files with 51 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/groff.texi
View File

@ -14347,10 +14347,11 @@ It is said that a trap is @dfn{sprung} if its condition is fulfilled.
@cindex vertical position traps
@cindex traps, vertical position
@dfn{Vertical position traps} perform an action when GNU @code{troff}
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.
A @dfn{vertical position trap} calls a macro when the formatter's
vertical drawing position reaches or passes, in the downward direction,
a certain location on the output page or in a diversion. Its
applications include setting page headers and footers, body text in
multiple columns, and footnotes.
@DefreqList {vpt, [@Var{flag}]}
@DefregListEndx {.vpt}
@ -14385,9 +14386,9 @@ Implicit Page Trap}.
@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.
A @dfn{page location trap} is a vertical position trap that applies to
the page; that is, to undiverted output. Many can be present; manage
them with the @code{wh} and @code{ch} requests.
@Defreq {wh, dist [@Var{name}]}
Plant macro @var{name} as page location trap at @var{dist}. The default
@ -14686,14 +14687,17 @@ are disabled with GNU @code{troff}'s @code{vpt} request.
@cindex diversion traps
@cindex traps, diversion
A diversion is not formatted in the context of a page, so it lacks page
location traps; instead it can have a @dfn{diversion trap}. There can
exist at most one such vertical position trap per diversion.
@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 at location @var{dist}, which is
interpreted relative to diversion rather than page boundaries. There
exists only a single diversion trap per diversion. If invoked with
interpreted relative to diversion rather than page boundaries. If invoked with
fewer than two arguments, any diversion trap in the current diversion is
removed. The register @code{.t} works within diversions. It is an
error to invoke @code{dt} in the top-level diversion.

47
man/groff.7.man
View File

@ -7189,6 +7189,17 @@ or conditions on the input that,
when reached or fulfilled,
call a specified macro.
.
A
.I "vertical position trap"
calls a macro when the formatter's vertical drawing position reaches or
passes,
in the downward direction,
a certain location on the output page or in a diversion.
.
Its applications include setting page headers and footers,
body text in multiple columns,
and footnotes.
.
These traps can occur at a given location on the page
.RB ( .wh ,\~ .ch );
at a given location in the current diversion
@ -7196,7 +7207,20 @@ at a given location in the current diversion
these are known as
vertical position traps,
which can be disabled and re-enabled
.RB ( .vpt );
.RB ( .vpt ).
.
.
.P
A diversion is not formatted in the context of a page,
so it lacks page location traps;
instead it can have a
.I "diversion trap."
.
There can exist at most one such vertical position trap per diversion.
.
.
.P
Other kinds of trap can be planted
at a blank line
.RB ( .blm );
at a line with leading space characters
@ -7246,14 +7270,19 @@ with its corresponding amount of motion
.\" ====================================================================
.
A
.I page location trap
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
.BR .ch ).
.I "page location trap"
is a vertical position trap that applies to
the page;
that is,
to undiverted output.
.
Many can be present;
manage them with
the
.B wh
and
.B ch
requests.
.
Non-negative page locations given to these requests set the trap
relative to the top of the page;