Manipulating Filling and Adjusting (The GNU Troff Manual)

5.7 Manipulating Filling and Adjusting

Various ways of causing breaks were given in Implicit Line Breaks. The br request likewise causes a break. Several other requests also cause breaks, but implicitly. These are bp, ce, cf, fi, fl, in, nf, rj, sp, ti, and trf.

Request: .br

Break the current line, i.e., the input collected so far is emitted without adjustment.

If the no-break control character is used, gtroff suppresses the break:

a
'br
b
    ⇒ a b

Initially, gtroff fills and adjusts text to both margins. Filling can be disabled via the nf request and re-enabled with the fi request.

Request: .fi

Activate fill mode (which is the default). This request implicitly enables adjusting; it also inserts a break in the text currently being filled. The read-only number register .u is set to 1.

The fill mode status is associated with the current environment (see Environments).

See Line Control, for interaction with the \c escape.

Request: .nf

Activate no-fill mode. Input lines are output as-is, retaining line breaks and ignoring the current line length. This command implicitly disables adjusting; it also causes a break. The number register .u is set to 0.

The fill mode status is associated with the current environment (see Environments).

See Line Control, for interaction with the \c escape.

Request: .ad [mode]

Set adjusting mode.

Activation and deactivation of adjusting is done implicitly with calls to the fi or nf requests.

mode can have one of the following values:

l: Adjust text to the left margin. This produces what is traditionally called ragged-right text.
r: Adjust text to the right margin, producing ragged-left text.
c: Center filled text. This is different to the ce request, which only centers text without filling.
b
n: Justify to both margins. This is the default used by gtroff.

Finally, mode can be the numeric argument returned by the .j register.

Using ad without argument is the same as saying .ad \[.j]. In particular, gtroff adjusts lines in the same way it did before adjusting was deactivated (with a call to na, say). For example, this input code

.de AD
.  br
.  ad \\$1
..
.
.de NA
.  br
.  na
..
.
textA
.AD r
.nr ad \n[.j]
textB
.AD c
textC
.NA
textD
.AD         \" back to centering
textE
.AD \n[ad]  \" back to right justifying
textF

produces the following output:

As just demonstrated, the current adjustment mode is available in the read-only number register .j; it can be stored and subsequently used to set adjustment.

The adjustment mode status is associated with the current environment (see Environments).

Request: .na

Disable adjusting. This request won’t change the current adjustment mode: A subsequent call to ad uses the previous adjustment setting.

The adjustment mode status is associated with the current environment (see Environments).

Request: .brp

Escape: \p

Break, adjusting the current line per the current adjustment mode.

With \p, this break will happen at the next word boundary. The \p itself is removed entirely, adding neither a break nor a space where it appears in input; it can thus be placed in the middle of a word to cause a break at the end of that word.

In most cases this produces very ugly results since gtroff doesn’t have a sophisticated paragraph building algorithm (as TeX has, for example); instead, gtroff fills and adjusts a paragraph line by line:

This is an uninteresting sentence.
This is an uninteresting sentence.\p
This is an uninteresting sentence.

is formatted as

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

Request: .ss word_space_size [sentence_space_size]

Change the size of a space between words. It takes its units as one twelfth of the space width parameter for the current font. Initially both the word_space_size and sentence_space_size are 12. In fill mode, the values specify the minimum distance.

If two arguments are given to the ss request, the second argument sets the sentence space size. If the second argument is not given, sentence space size is set to word_space_size. The sentence space size is used in two circumstances: If the end of a sentence occurs at the end of a line in fill mode, then both an inter-word space and a sentence space are added; if two spaces follow the end of a sentence in the middle of a line, then the second space is a sentence space. If a second argument is never given to the ss request, the behaviour of Unix troff is the same as that exhibited by GNU troff. In GNU troff, as in Unix troff, a sentence should always be followed by either a newline or two spaces.

The read-only number registers .ss and .sss hold the values of the parameters set by the first and second arguments of the ss request.

The word space and sentence space values are associated with the current environment (see Environments).

Contrary to AT&T troff, this request is not ignored if a TTY output device is used; the given values are then rounded down to a multiple of 12 (see Implementation Differences).

The request is ignored if there is no parameter.

Another useful application of the ss request is to insert discardable horizontal space, i.e., space that is discarded at a line break. For example, paragraph-style footnotes could be separated this way:

.ll 4.5i
1.\ This is the first footnote.\c
.ss 48
.nop
.ss 12
2.\ This is the second footnote.

The result:

1. This is the first footnote.        2. This
is the second footnote.

Note that the \h escape produces unbreakable space.

Request: .ce [nnn]

Center text. While the ‘.ad c’ request also centers text, it fills the text as well. ce does not fill the text it affects. This request causes a break. The number of lines still to be centered is associated with the current environment (see Environments).

The following example demonstrates the differences. Here is the input:

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

.ad c
This is a small text fragment that shows the differences
between the `.ce' and the `.ad c' request.

And here the result:

  This is a small text fragment that
         shows the differences
between the `.ce' and the `.ad c' request.

  This is a small text fragment that
shows the differences between the `.ce'
        and the `.ad c' request.

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

As can be seen in the previous example, it is a common idiom to turn on centering for a large number of lines, and to turn off centering after text to be centered. This is useful for any request that takes a number of lines as an argument.

The .ce read-only number register contains the number of lines remaining to be centered, as set by the ce request.

Request: .rj [nnn]
Register: \n[.rj]: Justify unfilled text to the right margin. Arguments are identical to the ce request. The .rj read-only number register is the number of lines to be right-justified as set by the rj request. This request causes a break. The number of lines still to be right-justified is associated with the current environment (see Environments).