Manipulating Filling and Adjustment (The GNU Troff Manual)

5.9 Manipulating Filling and Adjustment

When an output line is pending (see below), a break moves the drawing position to the beginning of the next text baseline, interrupting filling. Various ways of causing breaks were shown in Breaking. The br request likewise causes a break. Several other requests imply breaks: bp, ce, cf, fi, fl, in, nf, rj, sp, ti, and trf. If the no-break control character is used with any of these requests, GNU troff suppresses the break; instead the requested operation takes effect at the next break. ‘'br’ does nothing.

.ll 55n
This line is normally filled and adjusted.
.br
A line's alignment is decided
'ce \" Center the next input line (no break).
when it is output.
This line returns to normal filling and adjustment.
    ⇒ This line is normally filled and adjusted.
    ⇒    A line's alignment is decided when it is output.
    ⇒ This line returns to normal filling and adjustment.

Output line properties like page offset, indentation, adjustment, and even the location of its text baseline, are not determined until the line has been broken. An output line is said to be pending if some input has been collected but an output line corresponding to it has not yet been written; such an output line is also termed partially collected. If no output line is pending, it is as if a break has already happened; additional breaks, whether explicit or implicit, have no effect. If the vertical drawing position is negative—as it is when the formatter starts up—a break starts a new page (even if no output line is pending) unless an end-of-input macro is being interpreted. See End-of-input Traps.

Request: .br

Break the line: emit any pending output line without adjustment.

foo bar
.br
baz
'br
qux
    ⇒ foo bar
    ⇒ baz qux

Sometimes you want to prevent a break within a phrase or between a quantity and its units.

Escape sequence: \~

Insert an unbreakable space that is adjustable like an ordinary space. It is discarded from the end of an output line if a break is forced.

Set the output speed to\~1.
There are 1,024\~bytes in 1\~KiB.
J.\~F.\~Ossanna wrote the original CSTR\~#54.

By default, GNU troff fills text and adjusts it to reach the output line length. The nf request disables filling; the fi request reënables it.

Request: .fi
Register: \n[.u]: Enable filling of output lines; a pending output line is broken. The read-only register .u is set to 1. The filling enablement status, sometimes called fill mode, is associated with the environment (see Environments). See Line Continuation, for interaction with the \c escape sequence.

Request: .nf: Disable filling of output lines: the output line length (see Line Layout) is ignored and output lines are broken where the input lines are. A pending output line is broken and adjustment is suppressed. The read-only register .u is set to 0. The filling enablement status is associated with the environment (see Environments). See Line Continuation, for interaction with the \c escape sequence.

Request: .ad [mode]

Enable output line adjustment in mode, taking effect when the pending (or next) output line is broken. Adjustment is suppressed when filling is. mode can have one of the following values.

b
n: Adjust “normally”: if the output line does not consume the distance between the indentation and the configured output line length, GNU troff stretches adjustable spaces within the line until that length is reached. When the indentation is zero, this mode spreads the line to both the left and right margins. This is the GNU troff default.
c: Center filled text. Contrast with the ce request, which centers text without filling it.
l: Align text to the left without adjusting it.
r: Align text to the right without adjusting it.

mode can also be a value previously stored in the .j register. Using ad without an argument is the same as ‘.ad \n[.j]’; unless filling is disabled, GNU troff resumes adjusting lines in the same way it did before adjustment was disabled by invocation of the na request.

The adjustment mode and enablement status are encoded in the read-only register .j. These parameters are associated with the environment (see Environments).

The value of .j for any adjustment mode is an implementation detail and should not be relied upon as a programmer’s interface. Do not write logic to interpret or perform arithmetic on it.

.ll 48n
.de AD
.  br
.  ad \\$1
..
.de NA
.  br
.  na
..
left
.AD r
.nr ad \n(.j
right
.AD c
center
.NA
left
.AD
center
.AD \n(ad
right

    ⇒ left
    ⇒                                            right
    ⇒                      center
    ⇒ left
    ⇒                      center
    ⇒                                            right

Request: .na: Disable output line adjustment. This produces the same output as left-alignment, but the value of the adjustment mode register .j is altered differently. The adjustment mode and enablement status are associated with the environment (see Environments).

Request: .brp

Escape sequence: \p

Break, adjusting the line per the current adjustment mode. \p schedules a break with adjustment at the next word boundary. The escape sequence is itself neither a break nor a space of any kind; it can thus be placed in the middle of a word to cause a break at the end of that word.

Breaking with immediate adjustment can produce ugly results since GNU troff doesn’t have a sophisticated paragraph-building algorithm, as TeX has, for example. Instead, GNU troff fills and adjusts a paragraph line by line.

.ll 4.5i
This is an uninteresting sentence.
This is an uninteresting sentence.\p
This is an uninteresting sentence.

is formatted as follows.

This  is  an uninteresting sentence.  This is
an          uninteresting           sentence.
This is an uninteresting sentence.

To clearly present the next couple of requests, we must introduce the concept of “productive” input lines. A productive input line is one that directly produces formatted output. Text lines produce output,⁵³ as do control lines containing requests like tl or escape sequences like \D. Macro calls are not directly productive, and thus not counted, but their interpolated contents can be. Empty requests, and requests and escape sequences that define registers or strings or alter the formatting environment (as with changes to the size, face, height, slant, or color of the type) are not productive. We will also preview the output line continuation escape sequence, \c, which “connects” two input lines that would otherwise be counted separately. ⁵⁴

.de hello
Hello, world!
..
.ce \" center output of next productive input line
.
.nr junk-reg 1
.ft I
Chorus: \c
.ft
.hello
Went the day well?
  ⇒                  Chorus: Hello, world!
  ⇒ Went the day well?

Request: .ce [n]

Break (unless the no-break control character is used), center the output of the next n productive input lines with respect to the line length and indentation without filling, then break again regardless of the invoking control character. If the argument is not positive, centering is disabled. Omitting the argument implies an n of ‘1’. The count of lines remaining to be centered is stored in the read-only register .ce and is associated with the environment (see Environments).

While the ‘.ad c’ request also centers text, it fills the text as well.

.de FR
This is a small text fragment that shows the differences
between the `.ce' and the `.ad c' requests.
..
.ll 4i
.ce 1000
.FR
.ce 0

.ad c
.FR
    ⇒ This is a small text fragment that shows
    ⇒              the differences
    ⇒ between the ‘.ce’ and the ‘.ad c’ requests.
    ⇒
    ⇒ This is a small text fragment that shows
    ⇒  the differences between the ‘.ce’ and
    ⇒         the ‘.ad c’ requests.

The previous example illustrates a common idiom of turning centering on for a quantity of lines far in excess of what is required, and off again after the text to be centered. This technique relieves humans of counting lines for requests that take a count of input lines as an argument.

Request: .rj [n]

Break (unless the no-break control character is used), align the output of the next n productive input lines to the right margin without filling, then break again regardless of the control character. If the argument is not positive, right-alignment is disabled. Omitting the argument implies an n of ‘1’. The count of lines remaining to be right-aligned is stored in the read-only register .rj and is associated with the environment (see Environments).

.ll 49n
.rj 3
At first I hoped that such a technically unsound
project would collapse but I soon realized it was
doomed to success. \[em] C. A. R. Hoare
    ⇒  At first I hoped that such a technically unsound
    ⇒ project would collapse but I soon realized it was
    ⇒              doomed to success. -- C. A. R. Hoare

Request: .ss word-space-size [additional-sentence-space-size]

Set the sizes of spaces between words and sentences⁵⁵ in twelfths of font’s space width (typically one-fourth to one-third em for Western scripts). The default for both parameters is 12. Negative values are erroneous. The first argument is a minimum; if an output line undergoes adjustment, such spaces may increase in width. The optional second argument sets the amount of additional space separating sentences on the same output line. If omitted, this amount is set to word-space-size. The request is ignored if there are no parameters.

Additional inter-sentence space is used only if the output line is not full when the end of a sentence occurs in the input. If a sentence ends at the end of an input line, then both an inter-word space and an inter-sentence space are added to the output; if two spaces follow the end of a sentence in the middle of an input line, then the second space becomes an inter-sentence space in the output. Additional inter-sentence space is not adjusted, but the inter-word space that always precedes it may be. Further input spaces after the second, if present, are adjusted as normal.

The read-only registers .ss and .sss hold the minimal inter-word space and additional inter-sentence space amounts, respectively. These parameters are part of the environment (see Environments), and rounded down to the nearest multiple of 12 on terminals.

The ss request can insert discardable horizontal space; that is, space that is discarded at a break. For example, some footnote styles collect the notes into a single paragraph with large gaps between each note.

.ll 48n
1.\~J. Fict. Ch. Soc. 6 (2020), 3\[en]14.
.ss 12 48 \" applies to next sentence ending
Reprints no longer available through FCS.
.ss 12 \" go back to normal
2.\~Better known for other work.
    ⇒ 1.  J.  Fict. Ch. Soc. 6 (2020), 3-14.  Reprints
    ⇒ no longer available through FCS.      2.  Better
    ⇒ known for other work.

If undiscardable space is required, use the \h escape sequence.