Manipulating Filling and Adjustment (The GNU Troff Manual)

+Next: Manipulating Hyphenation, Previous: Registers, Up: GNU troff Reference [Contents][Index]

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

+ + + +