5.15 Line Layout

The following diagram shows the dimensions that the formatter uses to arrange a line of output on the page. Each dimension is labelled with the name of the request that configures it.

The dimensions are defined as follows.

The page offset can be thought of as the “left margin”. The right margin is not explicitly configured; the combination of page offset and line length provides the information necessary to derive it.

.ll 3i
This is text without indentation.
The line length has been set to 3\~inches.
.in +.5i
.ll -.5i
Now the left and right margins are both increased.
.in
.ll
Calling .in and .ll without parameters restores
the previous values.

    ⇒ This  is text without indenta-
    ⇒ tion.   The  line  length  has
    ⇒ been set to 3 inches.
    ⇒      Now   the  left  and
    ⇒      right  margins   are
    ⇒      both increased.
    ⇒ Calling  .in  and  .ll without
    ⇒ parameters restores the previ-
    ⇒ ous values.

Requests exist to place line numbers and margin characters within the page margins.¹⁵³

Request: .po [offset]

Request: .po +offset

Request: .po -offset

Register: \n[.o]

Set page offset to offset; if offset is signed, adjust the page offset by its value. The default scaling unit is ‘m’. The default offset is 1i on typesetters and zero on terminals. If offset is omitted, the formatter resets the page offset to that before the previous invocation of po, and zero if there is none. Read-only register ‘.o’ interpolates the page offset. This request is incorrectly documented in the AT&T troff manual as using a default scaling unit of ‘v’.

.po 3i
\n[.o]
    ⇒ 720
.po -1i
\n[.o]
    ⇒ 480
.po
\n[.o]
    ⇒ 720

Request: .in [indent]

Request: .in +indent

Request: .in -indent

Register: \n[.i]

Set indentation to indent; if indent is signed, adjust the indentation by its value. The default scaling unit is ‘m’. Initially, there is no indentation. This request causes a break. The indentation amount is associated with the environment.¹⁵⁴

If indent is omitted, the formatter resets the indentation to that before the previous invocation of in, and zero if there is none. If indent is negative, the formatter sets the indentation (and temporary indentation; see below) to zero.¹⁵⁵

The formatter delays the effect of in until it has emitted any partially collected line. In other words, in does not change a pending output line’s indentation.

The read-only register ‘.i’ interpolates the indentation amount, ignoring temporary indentation (see below).

Request: .ti [amount]

Request: .ti +amount

Request: .ti -amount

Register: \n[.in]

Temporarily indent the next output line by amount; if amount is signed, apply it as an offset to the indentation configured by the in request. The default scaling unit is ‘m’. This request causes a break. The effect of ti is delayed until a partially collected line (if it exists) is output. In other words, it does not change a pending output line’s indentation. The read-only register .in reports the total indentation that applies to the pending output line. The temporary indentation is associated with the environment.¹⁵⁶

If amount is omitted, GNU troff cancels any pending temporary indentation.

Idiomatic applications of the ti request are invocations by paragraphing macros; (1) to set up a first-line indentation of positive sign; and (2) to set up a “normal” temporary indentation of negative sign offsetting a posiitive indentation that applies to the whole parargraph, known as a “hanging indent”.

Request: .ll [length]

Request: .ll +length

Request: .ll -length

Register: \n[.l]

Register: \n[.ll]

Change (increase or decrease) the line length per the numeric expression length. The default scaling unit is ‘m’. If not otherwise configured (recall Paper Format), the default line length is 6.5i. If length is invalid, the formatter ignores the request. If length is nonpositive, the formatter sets the line length to the device’s horizontal motion quantum; recall Motion Quanta.¹⁵⁷ The line length is associated with the environment.¹⁵⁸ If length is omitted, the formatter restores the environment’s previous line length.

The effect of ll is delayed until a partially collected line (if it exists) is output. In other words, it does not change a pending output line’s length.

The line length as set by ll can be found in the read-only register ‘.l’. The read-only register .ll reports the line length that applies to the pending output line. Similarly to .i and .in, the difference between .l and .ll is that the latter takes into account whether a partially collected line still uses the previous length.