5.26 Output Line Annotation

After an output line is broken (and adjusted, if applicable), it can be annotated in the margins. You can indicate line numbers on the left, and apply a margin character on the right.

Request: .nm [start [increment [space [indentation]]]]

Register: \n[ln]

Register: \n[.nm]

Begin (or, with no arguments, cease) numbering output lines. start assigns the number of the next output line. Only line numbers divisible by increment (default: ‘1’) bear marks. The formatter reckons the third and fourth arguments in numeral widths (\0): space configures the horizontal spacing between the number and the text (default: ‘1’). Any given indentation applies to the numbers (default: ‘0’). start must be non-negative and increment positive.

The formatter aligns the number to the right in a space of three numeral widths plus indentation, then catenates space and the output line. The line length is not reduced. Depending on the value of the page offset (recall Line Layout) numbers wider than the allocated space protrude into the left margin, or shift the output line to the right.

Line numbering parameters corresponding to missing arguments are not altered. After numbering is disabled, ‘.nm +0’ resumes it using the previously active parameters.

The parameters of nm are associated with the environment (see Environments).

While numbering is enabled, the output line number register ln is updated as each line is output, even if no line number is formatted with it because it is being skipped (it is not a multiple of increment) or because numbering is suppressed (see the nn request below).

The .nm register tracks the enablement status of numbering. Temporary suspension of numbering with the nn request does not alter its value.

.po 5n
.ll 44n
Programming,
when stripped of all its circumstantial irrelevancies,
.nm 999 1 1 -4
boils down to no more and no less than
.nm +0 3
very effective thinking so as to avoid unmastered
.nn 2
complexity,
to very vigorous separation of your many
different concerns.
.br
\(em Edsger Dijkstra
.sp
.nm 1 1 1
This guy's arrogance takes your breath away.
.br
\(em John Backus
    ⇒      Programming,  when  stripped of all its cir-
    ⇒  999 cumstantial irrelevancies, boils down to  no
    ⇒      more  and no less than very effective think-
    ⇒      ing so as to avoid unmastered complexity, to
    ⇒      very vigorous separation of your  many  dif-
    ⇒      ferent concerns.
    ⇒ 1002 -- Edsger Dijkstra
    ⇒
    ⇒    1 This guy’s arrogance takes your breath away.
    ⇒    2 -- John Backus

Request: .nn [skip]

Register: \n[.nn]

Suppress numbering of the next skip output lines counted by the nm request. If skip is ‘0’, cancel suppression. The default is 1. nn can be invoked when line numbering is not active; suppression of numbering takes effect for skip lines once nm enables it.

The .nn register stores the count of lines remaining in the environment for which numbering is suppressed while output line numbering is enabled.

This count is associated with the environment (see Environments).

To test whether the current output line will be numbered, you must check both the .nm and .nn registers.

  .de is-numbered
  .  nop This line
  .  ie (\\n[.nm] & (1-\\n[.nn])) IS
  .  el                           ISN'T
  .  nop numbered.
  .  br
  ..
  Test line numbering.
  .is-numbered
  .nm 1
  .nn 1
  .is-numbered
  .is-numbered
  .nm
  .is-numbered
    ⇒ Test line numbering.  This line ISN’T numbered.
    ⇒ This line ISN’T numbered.
    ⇒   1 This line IS numbered.
    ⇒ This line ISN’T numbered.

Request: .mc [margin-character [distance]]

Begin (or, with no arguments, cease) writing a margin-character to the right of each output line. The distance argument separates margin-character from the right margin. If absent, the most recent value is used; the default is 10 points. If an output line exceeds the line length, the margin character is appended to it. No margin character is written on lines produced by the tl request.

The margin character is a property of the output line. Only one margin character is in effect at one time; the most recent mc call determines its value. If the margin character is disabled before an output line breaks, none is output (but see below).

The margin character is associated with the environment (see Environments).

.ll 5i
.nf
.mc \[br]
This paragraph is marked with a margin character.
.sp
As seen above, vertical space isn't thus marked.
\&
An output line that is present, but empty, is.
    ⇒ This paragraph is marked with a margin character.  |
    ⇒
    ⇒ As seen above, vertical space isn’t thus marked.   |
    ⇒                                                    |
    ⇒ An output line that is present, but empty, is.     |

For compatibility with AT&T troff, a call to mc to set the margin character can’t be undone immediately; at least one line gets a margin character.

.ll 10n
.nf
.mc |
.mc *
.mc
foo
bar
    ⇒ foo        *
    ⇒ bar

The margin character mechanism is commonly used to annotate changes in documents. The groff distribution ships a program, gdiffmk, to assist with this task.¹⁶⁰