Miscellaneous (The GNU Troff Manual)

5.35 Miscellaneous

We document here GNU troff features that fit poorly elsewhere.

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

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

The formatter aligns the number to the right in a width of three numeral spaces plus indentation, then catenates space and the output line. The line length is not reduced. Depending on the value of the page offset,¹¹⁷ 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]

Suppress numbering of the next skip output lines that would otherwise be numbered. The default is 1. nn can be invoked when line numbering is not active; suppression of numbering will take effect for skip lines once nm enables it.

The .nn register stores the count of output lines still to have their numbering suppressed.

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; the margin character last configured when the line is output controls. 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.¹¹⁸

Request: .psbb file

Retrieve the bounding box of the PostScript image found in file, which must conform to Adobe’s Document Structuring Conventions (DSC), locate a %%BoundingBox comment, and store the (upper-, lower-, -left, -right) values into the registers llx, lly, urx, and ury. If an error occurs (for example, if no %%BoundingBox comment is present), the formatter sets these registers to 0.

The search path for file can be controlled with the -I command-line option.