groff: Page Motions
5.25 Page Motions
=================
⇒Manipulating Spacing, for a discussion of the most commonly used
request for vertical motion, 'sp', which spaces downward by one vee.
-- Request: .mk [reg]
-- Request: .rt [dist]
You can "mark" a location on a page for subsequent "return". 'mk'
takes an argument, a register name in which to store the current
page location. If given no argument, it stores the location in an
internal register. This location can be used later by the 'rt' or
the 'sp' requests (or the '\v' escape).
The 'rt' request returns _upward_ to the location marked with the
last 'mk' request. If used with an argument, it returns to a
vertical position DIST from the top of the page (no previous call
to 'mk' is necessary in this case). The default scaling unit is
'v'.
If a page break occurs between a 'mk' request and its matching 'rt'
request, the 'rt' request is silently ignored.
A simple implementation of a macro to set text in two columns
follows.
.nr column-length 1.5i
.nr column-gap 4m
.nr bottom-margin 1m
.
.de 2c
. br
. mk
. ll \\n[column-length]u
. wh -\\n[bottom-margin]u 2c-trap
. nr right-side 0
..
.
.de 2c-trap
. ie \\n[right-side] \{\
. nr right-side 0
. po -(\\n[column-length]u + \\n[column-gap]u)
. \" remove trap
. wh -\\n[bottom-margin]u
. \}
. el \{\
. \" switch to right side
. nr right-side 1
. po +(\\n[column-length]u + \\n[column-gap]u)
. rt
. \}
..
Now let us apply our two-column macro.
.pl 1.5i
.ll 4i
This is a small test that shows how the
rt request works in combination with mk.
.2c
Starting here, text is typeset in two columns.
Note that this implementation isn't robust
and thus not suited for a real two-column
macro.
=> This is a small test that shows how the
=> rt request works in combination with mk.
=>
=> Starting here, isn't robust
=> text is typeset and thus not
=> in two columns. suited for a
=> Note that this real two-column
=> implementation macro.
Several escape sequences enable fine control of movement about the
page.
-- Escape sequence: \v'expr'
Vertically move the drawing position. EXPR indicates the magnitude
of motion: positive is downward and and negative upward. The
default scaling unit is 'v'. The motion is relative to the current
drawing position unless EXPR begins with the boundary-relative
motion operator '|'. ⇒Numeric Expressions.
Text processing continues at the new drawing position; usually,
vertical motions should be in balanced pairs to avoid a confusing
page layout.
'\v' will not spring a vertical position trap. This can be useful;
for example, consider a page bottom trap macro that prints a marker
in the margin to indicate continuation of a footnote. ⇒
Traps.
A few escape sequences that produce vertical motion are unusual.
They are thought to originate early in AT&T 'nroff' history to achieve
super- and subscripting by half-line motions on line printers and
teletypewriters before the phototypesetter made more precise positioning
available. They are reckoned in ems--not vees--to maintain continuity
with their original purpose of moving relative to the size of the type
Motions-Footnote-1::)
-- Escape sequence: \r
-- Escape sequence: \u
-- Escape sequence: \d
Move upward 1m, upward .5m, and downward .5m, respectively.
Let us see these escape sequences in use.
Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU.
In the foregoing we have paired '\u' and '\d' to typeset a
superscript, and later a full em negative ("reverse") motion to place a
superscript above a subscript. A numeral-width horizontal motion escape
sequence aligns the proton and nucleon numbers, while '\k' marks a
horizontal position to which '\h' returns so that we could stack them.
(We shall discuss these horizontal motion escape sequences presently.)
In serious applications, we often want to alter the type size of the
-scripts and to fine-tune the vertical motions, as the 'groff' 'ms'
package does with its super- and subscripting string definitions.
-- Escape sequence: \h'expr'
Horizontally move the drawing position. EXPR indicates the
magnitude of motion: positive is rightward and negative leftward.
The default scaling unit is 'm'. The motion is relative to the
current drawing position unless EXPR begins with the
boundary-relative motion operator '|'. ⇒Numeric
Expressions.
Motions-Footnote-2::)
.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
There are a number of special-case escape sequences for horizontal
motion.
-- Escape sequence: \<SP>
Move right one word space. (The input is a backslash followed by a
space.) This escape sequence can be thought of as a
non-adjustable, unbreakable space. Usually you want '\~' instead;
see ⇒Manipulating Filling and Adjustment.
-- Escape sequence: \|
Move one-sixth em to the right on typesetting output devices. If a
glyph named '\|' is defined in the current font, its width is used
instead, even on terminal output devices.
-- Escape sequence: \^
Move one-twelfth em to the right on typesetting output devices. If
a glyph named '\^' is defined in the current font, its width is
used instead, even on terminal output devices.
-- Escape sequence: \0
Move right by the width of a numeral in the current font.
Horizontal motions are not discarded at the end of an output line as
word spaces are. ⇒Breaking.
-- Escape sequence: \w'anything'
-- Register: \n[st]
-- Register: \n[sb]
-- Register: \n[rst]
-- Register: \n[rsb]
-- Register: \n[ct]
-- Register: \n[ssc]
-- Register: \n[skw]
Interpolate the width of ANYTHING in basic units. This escape
sequence allows several properties of formatted output to be
measured without writing it out.
The length of the string 'abc' is \w'abc'u.
=> The length of the string 'abc' is 72u.
ANYTHING is processed in a dummy environment: this means that font
and type size changes, for example, may occur within it without
affecting subsequent output.
After each use, '\w' sets several registers.
'st'
'sb'
The maximum vertical displacements of the text baseline above
and below, respectively. The sign convention is opposite that
of relative vertical motions; that is, depth below the
(original) baseline is negative. These registers are
incorrectly documented in the AT&T 'troff' manual as "the
highest and lowest extent of [the argument to '\w'] relative
to the baseline".
'rst'
'rsb'
Like 'st' and 'sb', but taking account of the heights and
depths of glyphs. In other words, these registers store the
highest and lowest vertical positions attained by ANYTHING,
doing what AT&T 'troff' documented 'st' and 'sb' as doing.
'ct'
Characterizes the geometry of glyphs occurring in ANYTHING.
0
only short glyphs, no descenders or tall glyphs
1
at least one descender
2
at least one tall glyph
3
at least one each of a descender and a tall glyph
'ssc'
The amount of horizontal space (possibly negative) that should
be added to the last glyph before a subscript.
'skw'
How far to right of the center of the last glyph in the '\w'
argument, the center of an accent from a roman font should be
placed over that glyph.
-- Escape sequence: \kp
-- Escape sequence: \k(ps
-- Escape sequence: \k[position]
Store the current horizontal position in the _input_ line in a
register with the name POSITION (one-character name P,
two-character name PS). Use this, for example, to return to the
beginning of a string for highlighting or other decoration.
-- Register: \n[hp]
The current horizontal position at the input line.
-- Register: \n[.k]
A read-only register containing the current horizontal output
position (relative to the current indentation).
-- Escape sequence: \o'abc...'
Overstrike the glyphs of characters A, B, C, ...; the glyphs are
centered, written, and the drawing position advanced by the widest
of the glyphs.
-- Escape sequence: \zc
Format the character C with zero width; that is, without advancing
the drawing position. Use '\z' to overstrike glyphs aligned to
their left edges, in contrast to '\o''s centering.
-- Escape sequence: \Z'anything'
Save the drawing position, format ANYTHING, then restore it. Tabs
and leaders in the argument are ignored with an error diagnostic.
We might implement a strike-through macro thus.
.de ST
.nr width \w'\\$1'
\Z@\v'-.25m'\l'\\n[width]u'@\\$1
..
.
This is
.ST "a test"
an actual emergency!