Page Motions (The GNU Troff Manual)

5.25 Page Motions

See 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 ‘|’. See 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. See 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 rather than the distance between text baselines (vees).¹⁰³

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 ‘|’. See Numeric Expressions.

The following string definition sets the TeX logo.¹⁰⁴

.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. See Breaking.

Escape sequence: \w'anything'

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[.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!