1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<!-- This manual documents GNU troff version 1.23.0.
Copyright � 1994-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU Free
Documentation License". -->
<title>Page Location Traps (The GNU Troff Manual)</title>
<meta name="description" content="Page Location Traps (The GNU Troff Manual)">
<meta name="keywords" content="Page Location Traps (The GNU Troff Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Request-Index.html" rel="index" title="Request Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Vertical-Position-Traps.html" rel="up" title="Vertical Position Traps">
<link href="The-Implicit-Page-Trap.html" rel="next" title="The Implicit Page Trap">
<link href="Vertical-Position-Traps.html" rel="prev" title="Vertical Position Traps">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
</head>
<body lang="en">
<div class="subsubsection-level-extent" id="Page-Location-Traps">
<div class="nav-panel">
<p>
Next: <a href="The-Implicit-Page-Trap.html" accesskey="n" rel="next">The Implicit Page Trap</a>, Previous: <a href="Vertical-Position-Traps.html" accesskey="p" rel="prev">Vertical Position Traps</a>, Up: <a href="Vertical-Position-Traps.html" accesskey="u" rel="up">Vertical Position Traps</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsubsection" id="Page-Location-Traps-1">5.28.1.1 Page Location Traps</h4>
<a class="index-entry-id" id="index-page-location-traps"></a>
<a class="index-entry-id" id="index-traps_002c-page-location"></a>
<p>A <em class="dfn">page location trap</em> is a vertical position trap that applies to
the page; that is, to undiverted output. Many can be present; manage
them with the <code class="code">wh</code> and <code class="code">ch</code> requests.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ewh"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.wh</code></strong> <var class="def-var-arguments">dist [<span class="r"><i class="slanted">name</i></span>]</var><a class="copiable-link" href='#index-_002ewh'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-wh"></a>
<p>Plant macro <var class="var">name</var> as page location trap at <var class="var">dist</var>. The default
scaling unit is ‘<samp class="samp">v</samp>’. Non-negative values for <var class="var">dist</var> 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 class="var">dist</var> of <code class="code">-0</code>
is interpreted as <code class="code">0</code>, the top of the page.<a class="footnote" id="DOCF106" href="groff.html_fot.html#FOOT106"><sup>106</sup></a> An existing <em class="emph">visible</em> trap (see below) at
<var class="var">dist</var> is removed; this is <code class="code">wh</code>’s sole function if <var class="var">name</var>
is missing.
</p>
<p>A trap is sprung only if it is <em class="dfn">visible</em>, meaning that its location
is reachable on the page<a class="footnote" id="DOCF107" href="groff.html_fot.html#FOOT107"><sup>107</sup></a> and it
is not hidden by another trap at the same location already planted
there.
</p>
<a class="index-entry-id" id="index-page-headers"></a>
<a class="index-entry-id" id="index-page-footers"></a>
<a class="index-entry-id" id="index-headers-1"></a>
<a class="index-entry-id" id="index-footers-1"></a>
<a class="index-entry-id" id="index-top-margin"></a>
<a class="index-entry-id" id="index-margin_002c-top"></a>
<a class="index-entry-id" id="index-bottom-margin"></a>
<a class="index-entry-id" id="index-margin_002c-bottom"></a>
<p>A macro package might set headers and footers as follows; this example
configures vertical margins of one inch to the body text, and one
half-inch to the titles. Observe the use of the no-break control
character with <code class="code">sp</code> request to position our text baselines,
and the page number character ‘<samp class="samp">%</samp>’ used with the <code class="code">tl</code> request.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.\" hdfo.roff
.de hd \" page header
' sp .5i
' tl '\\*(Ti''\\*(Da' \" title and date strings
' sp .5i
..
.de fo \" page footer
' sp .5i
. tl ''%''
. bp
..
.wh 0 hd \" trap at top of the page
.wh -1i fo \" trap 1 inch from bottom
</pre></div></div>
<p>To use these traps, copy the above (or load it from a file with the
<code class="code">so</code> or <code class="code">mso</code> requests), then set up the strings it uses.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.so hdfo.roff
.ds Ti Final Report\"
.ds Da 21 May 2023\"
.ti
On 5 August of last year,
this committee tasked me with the investigation of the
CFIT (controlled flight into terrain) incident of
.\" <i class="i">...and so on...</i>
</pre></div></div>
<p>A trap above the top or at or below the bottom of the page can be made
visible by either moving it into the page area or increasing the page
length so that the trap is on the page. Negative trap values always use
the <em class="emph">current</em> page length; they are not converted to an absolute
vertical position.
<a class="index-entry-id" id="index-page-location-traps_002c-debugging"></a>
<a class="index-entry-id" id="index-debugging-page-location-traps"></a>
We can use the <code class="code">ptr</code> request to dump our page location traps to the
standard error stream (see <a class="pxref" href="Debugging.html">Debugging</a>). Their positions are reported
in basic units; an <code class="code">nroff</code> device example follows.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.pl 5i
.wh -1i xx
.ptr
error→ xx -240
.pl 100i
.ptr
error→ xx -240
</pre></div></div>
<p>It is possible to have more than one trap at the same location (although
only one at a time can be visible); to achieve this, the traps must be
defined at different locations, then moved to the same place with the
<code class="code">ch</code> request. In the following example, the many empty lines
caused by the <code class="code">bp</code> request are not shown in the output.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de a
. nop a
..
.de b
. nop b
..
.de c
. nop c
..
.
.wh 1i a
.wh 2i b
.wh 3i c
.bp
⇒ a b c
</pre></div></div>
<div class="example">
<div class="group"><pre class="example-preformatted">.ch b 1i
.ch c 1i
.bp
⇒ a
</pre></div></div>
<div class="example">
<div class="group"><pre class="example-preformatted">.ch a 0.5i
.bp
⇒ a b
</pre></div></div>
</dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_005cn_005b_002et_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.t]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002et_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_002et"></a>
<a class="index-entry-id" id="index-distance-to-next-vertical-position-trap-register-_0028_002et_0029"></a>
<a class="index-entry-id" id="index-trap_002c-distance-to-next-vertical-position_002c-register-_0028_002et_0029"></a>
<p>The read-only register <code class="code">.t</code> holds the distance to the next vertical
position trap. If there are no traps between the current position and
the bottom of the page, it contains the distance to the page bottom.
Within a diversion, in the absence of a diversion trap, this distance is
the largest representable integer in basic units—effectively infinite.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002ech"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.ch</code></strong> <var class="def-var-arguments">name [<span class="r"><i class="slanted">dist</i></span>]</var><a class="copiable-link" href='#index-_002ech'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-ch"></a>
<a class="index-entry-id" id="index-changing-trap-location-_0028ch_0029"></a>
<a class="index-entry-id" id="index-trap_002c-changing-location-_0028ch_0029"></a>
<p>Change the location of a trap by moving macro <var class="var">name</var> to new location
<var class="var">dist</var>, or by unplanting it altogether if <var class="var">dist</var> is absent. The
default scaling unit is ‘<samp class="samp">v</samp>’. Parameters to <code class="code">ch</code> are specified
in the opposite order from <code class="code">wh</code>. If <var class="var">name</var> 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.<a class="footnote" id="DOCF108" href="groff.html_fot.html#FOOT108"><sup>108</sup></a>
</p>
<p>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.
</p>
</dd></dl>
<p>The same macro can be installed simultaneously at multiple locations;
however, only the earliest-planted instance—that has not yet been
deleted with <code class="code">wh</code>—will be moved by <code class="code">ch</code>. The following
example (using an <code class="code">nroff</code> device) illustrates this behavior. Blank
lines have been elided from the output.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de T
Trap sprung at \\n(nlu.
.br
..
.wh 1i T
.wh 2i T
foo
.sp 11i
.bp
.ch T 4i
bar
.sp 11i
.bp
.ch T 5i
baz
.sp 11i
.bp
.wh 5i
.ch T 6i
qux
.sp 11i
</pre></div></div>
<div class="example">
<div class="group"><pre class="example-preformatted"> ⇒ foo
⇒ Trap sprung at 240u.
⇒ Trap sprung at 480u.
⇒ bar
⇒ Trap sprung at 480u.
⇒ Trap sprung at 960u.
⇒ baz
⇒ Trap sprung at 480u.
⇒ Trap sprung at 1200u.
⇒ qux
⇒ Trap sprung at 1440u.
</pre></div></div>
<dl class="first-deffn">
<dt class="deffn" id="index-_005cn_005b_002ene_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.ne]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002ene_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_002ene-1"></a>
<p>The read-only register <code class="code">.ne</code> contains the amount of space that was
needed in the last <code class="code">ne</code> request that caused a trap to be sprung;
it is useful in conjunction with the <code class="code">.trunc</code> register. See <a class="xref" href="Page-Control.html">Page Control</a>. Since the <code class="code">.ne</code> register is set only by traps, it
doesn’t make sense to interpolate it outside of macros called by traps.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_005cn_005b_002etrunc_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.trunc]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002etrunc_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_002etrunc"></a>
<a class="index-entry-id" id="index-ne-request_002c-and-the-_002etrunc-register"></a>
<a class="index-entry-id" id="index-truncated-vertical-space-register-_0028_002etrunc_0029"></a>
<p>A read-only register containing the amount of vertical space truncated
from an <code class="code">sp</code> request by the most recently sprung vertical
position trap, or, if the trap was sprung by an <code class="code">ne</code> request,
minus the amount of vertical motion produced by the <code class="code">ne</code>
request. In other words, at the point a trap is sprung, it
represents the difference of what the vertical position would have
been but for the trap, and what the vertical position actually is.
Since the <code class="code">.trunc</code> register is set only by traps, it doesn’t make
sense to interpolate it outside of macros called by traps.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_005cn_005b_002epe_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.pe]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002epe_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_002epe"></a>
<a class="index-entry-id" id="index-bp-request_002c-and-traps-_0028_002epe_0029"></a>
<a class="index-entry-id" id="index-traps_002c-sprung-by-bp-request-_0028_002epe_0029"></a>
<a class="index-entry-id" id="index-page-ejection-status-register-_0028_002epe_0029"></a>
<p>This Boolean-valued, read-only register interpolates 1 while a page
is being ejected, and 0 otherwise.
</p>
<p>In the following example, we plant the same trap at the top and the
bottom of the page. We also make the trap report its name and the
vertical drawing position.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de T
.tm \\$0: page \\n%, nl=\\n[nl] .pe=\\n[.pe]
..
.ll 46n
.wh 0 T
.wh -1v T
Those who can make you believe absurdities can make you
commit atrocities. \[em] Voltaire
error→ T: page 1, nl=0 .pe=0
error→ T: page 1, nl=2600 .pe=1
⇒ Those who can make you believe absurdities can
⇒ make you commit atrocities. -- Voltaire
</pre></div></div>
</dd></dl>
<a class="index-entry-id" id="index-diversions_002c-and-traps"></a>
<a class="index-entry-id" id="index-traps_002c-and-diversions"></a>
<p>When designing macros, keep in mind that diversions and traps do
normally interact. For example, if a trap calls a header macro (while
outputting a diversion) that tries to change the font on the current
page, the effect is not visible before the diversion has completely been
printed (except for input protected with <code class="code">\!</code> or <code class="code">\?</code>) since
the data in the diversion is already formatted. In most cases, this is
not the expected behaviour.
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="The-Implicit-Page-Trap.html">The Implicit Page Trap</a>, Previous: <a href="Vertical-Position-Traps.html">Vertical Position Traps</a>, Up: <a href="Vertical-Position-Traps.html">Vertical Position Traps</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
