The GNU Troff Manual: Page Motions

5.22 Page Motions

See Manipulating Spacing, for a discussion of the main request for vertical motion, sp.

Request: .mk [reg]

Request: .rt [dist]

The request mk can be used to mark a location on a page, for movement to later. This request takes a register name as an argument in which to store the current page location. With no argument it stores the location in an internal register. The results of this can be used later by the rt or the sp request (or the \v escape).

The rt request returns upwards to the location marked with the last mk request. If used with an argument, return to a position which distance from the top of the page is dist (no previous call to mk is necessary in this case). Default scaling indicator is ‘v’.

Here a primitive solution for a two-column macro.

.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
.  \}
..
.

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

Result:

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.

The following escapes give fine control of movements about the page.

Escape: \v'e'

Move vertically, usually from the current location on the page (if no absolute position operator ‘|’ is used). The argument e specifies the distance to move; positive is downwards and negative upwards. The default scaling indicator for this escape is ‘v’. Beware, however, that gtroff continues text processing at the point where the motion ends, so you should always balance motions to avoid interference with text processing.

\v doesn’t trigger a trap. This can be quite useful; for example, consider a page bottom trap macro that prints a marker in the margin to indicate continuation of a footnote or something similar.

There are some special-case escapes for vertical motion.

Escape: \r: Move upwards 1v.

Escape: \u: Move upwards .5v.

Escape: \d: Move down .5v.

Escape: \h'e'

Move horizontally, usually from the current location (if no absolute position operator ‘|’ is used). The expression e indicates how far to move: positive is rightwards and negative leftwards. The default scaling indicator for this escape is ‘m’.

This horizontal space is not discarded at the end of a line. To insert discardable space of a certain length use the ss request.

There are a number of special-case escapes for horizontal motion.

Escape: \SP: An unbreakable and unpaddable (i.e. not expanded during filling) space. (Note: This is a backslash followed by a space.)

Escape: \~: An unbreakable space that stretches like a normal inter-word space when a line is adjusted.

Escape: \|

A 1/6th em space. Ignored for TTY output devices (rounded to zero).

However, if there is a glyph defined in the current font file with name \| (note the leading backslash), the width of this glyph is used instead (even for TTYs).

Escape: \^

A 1/12th em space. Ignored for TTY output devices (rounded to zero).

However, if there is a glyph defined in the current font file with name \^ (note the leading backslash), the width of this glyph is used instead (even for TTYs).

Escape: \0: A space the size of a digit.

The following string sets the TeX logo:

.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X

Escape: \w'text'

Return the width of the specified text in basic units. This allows horizontal movement based on the width of some arbitrary text (e.g. given as an argument to a macro).

The length of the string `abc' is \w'abc'u.
    ⇒ The length of the string `abc' is 72u.

Font changes may occur in text, which don’t affect current settings.

After use, \w sets several registers:

st

sb

The highest and lowest point of the baseline, respectively, in text.

rst

rsb

Like the st and sb registers, but takes account of the heights and depths of glyphs. In other words, this gives the highest and lowest point of text. Values below the baseline are negative.

ct

Defines the kinds of glyphs occurring in text:

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: \kp
Escape: \k(ps
Escape: \k[position]: Store the current horizontal position in the input line in number register with 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 number register containing the current horizontal output position (relative to the current indentation).

Escape: \o'abc': Overstrike glyphs a, b, c, …; the glyphs are centered, and the resulting spacing is the largest width of the affected glyphs.

Escape: \zg: Print glyph g with zero width, i.e., without spacing. Use this to overstrike glyphs left-aligned.

Escape: \Z'anything'

Print anything, then restore the horizontal and vertical position. The argument may not contain tabs or leaders.

The following is an example of a strike-through macro:

.de ST
.nr ww \w'\\$1'
\Z@\v'-.25m'\l'\\n[ww]u'@\\$1
..
.
This is
.ST "a test"
an actual emergency!