5.11 Manipulating Spacing

A break causes the formatter to update the vertical drawing position at which the new text baseline is placed; you can alter this location.

Request: .sp [distance]

Break and move the next text baseline down by distance, or until springing a page location trap.75 If invoked with the no-break control character, sp moves the text baseline applied to the entire pending output line by distance.76 A negative distance will not reduce the position of the text baseline below zero. Inside a diversion, any distance argument is ignored. The default scaling unit is ‘v’. If distance is not specified, ‘1v’ is assumed.

.pl 5v \" Set page length to 5 vees.
.de xx
\-\-\-
.  br
..
.wh 0 xx \" Set a trap at the top of the page.
foo on page \n%
.sp 2v
bar on page \n%
.sp 50v \" This will cause a page break.
baz on page \n%
.pl \n(nlu \" Truncate page to current position.
    ⇒ ---
    ⇒ foo on page 1
    ⇒
    ⇒
    ⇒ bar on page 1
    ⇒ ---
    ⇒ baz on page 2

The following macros place the next text baseline relative to the page top or bottom. We subtract one line height (\n[.v]) because the | operator moves the drawing position relative to the first baseline on the page (recall Numeric Expressions).

.de y-from-top-down
.  sp |\\$1-\\n[.v]u
..
.de y-from-bot-up
.  sp |\\n[.p]u-\\$1-\\n[.v]u
..

The input ‘.y-from-bot-up 10c’ sets the next text baseline 10 cm from the bottom edge of the paper.

Request: .ls [count]
Register: \n[.L]

Set the line spacing; add count−1 blank lines after each line of text. With no argument, GNU troff uses the previous value before the last ls call. The default is 1.

The read-only register .L contains the current line spacing; it is associated with the environment (see Environments).

The ls request is a coarse mechanism. See Changing the Type Size, for the requests vs and pvs as alternatives to ls.

.de SetNewLineSpacing
.  if r *old-vs .ab cannot nest SetNewLineSpacing
.  nr *old-vs \\n[.v]
.  vs (\\n[.v] * \\$1)
..
.
.de RestoreOldLineSpacing
.  vs \\n[*old-vs]
.  rr *old-vs
..
Escape sequence: \x'spacing'
Register: \n[.a]

Sometimes, an output line requires additional vertical spacing, for instance to allow room for a tall construct like an inline equation with exponents or subscripts (particularly if they are iterated). The \x escape sequence takes a delimited measurement (like ‘\x'3p'’) to increase the vertical spacing of the pending output line. The default scaling unit is ‘v’. If the measurement is positive, extra vertical space is inserted below the current line; a negative measurement adds space above. If \x is applied to the pending output line multiple times, the maxima of the positive and negative adjustments are separately applied. The delimiter need not be a neutral apostrophe; see Delimiters.

The .a read-only register contains the extra vertical spacing after the text baseline of the most recently emitted output line. (In other words, it is the largest positive argument to \x encountered on that line.) This quantity is exposed via a register because if an output line requires this “extra post-vertical line spacing”, and the subsequent output line requires “extra pre-vertical line spacing” (a negative argument to \x), then applying both can lead to excessive spacing between the output lines. Text that is piling high on line n might not require (as much) extra pre-vertical line spacing if line n−1 carries extra post-vertical line spacing.

Use of \x can be necessary in combination with the bracket-building escape sequence \b,77 as the following example shows.

.nf
This is a test of \[rs]b (1).
This is a test of \[rs]b (2).
This is a test of \b'xyz'\x'-1m'\x'1m' (3).
This is a test of \[rs]b (4).
This is a test of \[rs]b (5).
    ⇒ This is a test of \b (1).
    ⇒ This is a test of \b (2).
    ⇒                   x
    ⇒ This is a test of y (3).
    ⇒                   z
    ⇒ This is a test of \b (4).
    ⇒ This is a test of \b (5).

Without \x, the backslashes on the lines marked ‘(2)’ and ‘(4)’ would be overprinted.

Request: .ns
Request: .rs
Register: \n[.ns]

Enable no-space mode. Vertical spacing, whether by sp requests or blank input lines, is disabled. The bp request to advance to the next page is also disabled, unless it is accompanied by a page number (see Page Control). No-space mode ends automatically when text78 is formatted for output 79 or the rs request is invoked, which ends no-space mode. The read-only register .ns interpolates a Boolean value indicating the enablement of no-space mode.

A paragraphing macro might ordinarily insert vertical space to separate paragraphs. A section heading macro could invoke ns to suppress this spacing for the first paragraph in a section.