5.8.1 Setting Registers

Define registers and update their values with the nr request or the \R escape sequence.

Request: .nr ident value

Escape sequence: \R'ident value'

Set register ident to value. If ident doesn’t exist, the formatter creates it. In the \R escape sequence, the delimiter need not be a neutral apostrophe; recall Delimiters.

.nr a (((17 + (3 * 4))) % 4)
\n[a]
.\R'a (((17 + (3 * 4))) % 4)'
\n[a]
    ⇒ 1 1

Later, we will discuss additional forms of nr and \R that can change a register’s value after it is dereferenced but before it is interpolated.¹⁰⁸

GNU troff does not tokenize \R when reading it; the escape sequence updates only the formatter’s register dictionary and does not contribute (directly) to output.¹⁰⁹

Further surprise can occur if you use registers like .k,¹¹⁰ whose values are not determined until they are interpolated.

.ll 1.6i
.
aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]'
.tm :k == \n[:k]
    ⇒ :k == 126950
.
.br
.
aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]'
.tm :k == \n[:k]
    ⇒ :k == 15000

If you process this with the PostScript device (-T ps), there will be a line break eventually after ggg in both input lines. However, after processing the space after ggg, the partially collected line is not overfull yet, so GNU troff continues to collect input until it sees the space (or in this case, the newline) after hhh. At this point, the line is longer than the line length, and the line gets broken.

In the first input line, since the \R escape sequence leaves no traces, the check for the overfull line hasn’t been done yet at the point where \R gets handled, and you get a value for the .k register that is even greater than the current line length.

In the second input line, the insertion of \h'0' to cause a zero-width motion forces GNU troff to check the line length, which in turn causes the start of a new output line. Now .k returns the expected value.

nr and \R each have two additional special forms to increment or decrement a register.

Request: .nr ident +value

Request: .nr ident -value

Escape sequence: \R'ident +value'

Escape sequence: \R'ident -value'

Increment (decrement) register ident by value. In the \R escape sequence, the delimiter need not be a neutral apostrophe; recall Delimiters.

.nr a 1
.nr a +1
\na
    ⇒ 2

A roff formatter always interprets a leading minus sign in value as a decrementation operator, not an algebraic sign. To assign a register a negative value or the negated value of another register, you must force the formatter to interpret ‘-’ as a negation or minus, rather than decrementation, operator: enclose the ‘-’ with its operand in parentheses or subtract the expression of interest from zero.

.nr a 7
.nr b 3
.nr a -\nb
\na
    ⇒ 4
.nr a (-\nb)
\na
    ⇒ -3
.nr a 0-\nb
\na
    ⇒ -3

If reg is undefined, the formatter creates it and applies an increment or decrement to it as if to 0.

Request: .rr reg …

Remove each register reg. Technically, only the name is removed; the register’s contents are still accessible under aliases created with aln, if any. If reg is undefined, the formatter ignores the request.¹¹¹

This request is incorrectly documented in the AT&T troff manual as accepting only one argument.

Request: .rnn ident1 ident2

Rename register ident1 to ident2. Renaming a built-in register does not otherwise alter its properties. If ident1 is undefined, GNU troff ignores the request.¹¹²

Request: .aln new-register existing-register

Create alias (additional name) new-register of existing-register, causing the names to refer to the same stored object. If existing-register is undefined, GNU troff ignores the request.¹¹³

To remove a register alias, invoke rr on its name. A register’s contents do not become inaccessible until it has no more names.