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, and adjustment 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 both margins. Filling can be disabled via the nf request and re-enabled with the fi request.

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]
Register: \n[.j]

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”: to both 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 margin, producing what is sometimes called ragged-right text.

r

Align text to the right margin, producing ragged-left text.

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.

.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

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.

Request: .na

Disable output line adjustment. This produces the same output as alignment to the left margin, 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. The output line continuation escape sequence \c “connects” two input lines that would otherwise be counted separately. See Line Continuation.

.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 [nnn]
Register: \n[.ce]

Break (unless the no-break control character is used), center the output of the next nnn productive input lines without filling, then break again (regardless of the control character). 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. The following example demonstrates the difference.

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

With no arguments, ce centers the next line of text. nnn specifies the number of lines to be centered. If the argument is zero or negative, centering is disabled.

The basis for centering text is the line length (as set with the ll request) minus the indentation (as set with the in request). Temporary indentation is ignored.

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 [nnn]
Register: \n[.rj]

Break (unless the no-break control character is used), align the output of the next nnn productive input lines to the right margin without filling, then break again (regardless of the control character). The count of lines remaining to be centered is stored in the read-only register .rj and is associated with the environment (see Environments).

Request: .ss word-space-size [additional-sentence-space-size]
Register: \n[.ss]
Register: \n[.sss]

Set the sizes of spaces between words and sentences.49 Their units are twelfths of the space width of the current font. Initially both the word-space-size and additional-sentence-space-size are 12. Negative values are not permitted. The request is ignored if there are no arguments.

The first argument, the inter-word space size, 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 read-only registers .ss and .sss hold the values of minimal inter-word space and additional inter-sentence space, respectively. These parameters are associated with the environment (see Environments), and rounded down to the nearest multiple of 12 on terminal output devices.

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.

A related application of the ss request is to insert discardable horizontal space; i.e., space that is discarded at a line break. For example, some footnote styles collect the notes into a single paragraph with large spaces between each.

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