info groff

File: groff.info, Node: Manipulating Filling and Adjustment, Next: Manipulating Hyphenation, Prev: Registers, Up: GNU troff Reference

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 *note 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.
*Note 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 (*note Environments::). *Note Line Continuation::, for
interaction with the '\c' escape sequence.

-- Request: .nf
Disable filling of output lines: the output line length (*note 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 (*note
Environments::). See *note 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": 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 (*note 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 (*note 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,(1)
(*note Manipulating Filling and Adjustment-Footnote-1::) 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. (2) (*note
Manipulating Filling and Adjustment-Footnote-2::)

.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]
-- Register: \n[.ce]
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 (*note 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]
-- Register: \n[.rj]
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 (*note
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]
-- Register: \n[.ss]
-- Register: \n[.sss]
Set the sizes of spaces between words and sentences(3) (*note
Manipulating Filling and Adjustment-Footnote-3::) 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 (*note
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.