5.35 Miscellaneous

This section documents parts of gtroff that cannot (yet) be categorized elsewhere in this manual.

Request: .nm [start [inc [space [indent]]]]
Register: \n[ln]
Register: \n[.nm]

Print line numbers. start is the line number of the next output line. inc indicates which line numbers are printed. For example, the value 5 means to emit only line numbers that are multiples of 5; this defaults to 1. space is the space to be left between the number and the text; this defaults to one digit space. The fourth argument is the indentation of the line numbers, defaulting to zero. Both space and indent are given as multiples of digit spaces; they can be negative also. Without any arguments, line numbers are turned off.

gtroff reserves three digit spaces for the line number (which is printed right-justified) plus the amount given by indent; the output lines are concatenated to the line numbers, separated by space, and without reducing the line length. Depending on the value of the horizontal page offset (as set with the po request), line numbers that are longer than the reserved space stick out to the left, or the whole line is moved to the right.

Parameters corresponding to missing arguments are not changed; any non-digit argument (to be more precise, any argument starting with a character valid as a delimiter for identifiers) is also treated as missing.

If line numbering has been disabled with a call to nm without an argument, it can be reactivated with ‘.nm +0’, using the previously active line numbering parameters.

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

While line 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 inc) or because numbering is suppressed (see the nn request below).

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

.po 1m
.ll 2i
This test shows how line numbering works with groff.
.nm 999
This test shows how line numbering works with groff.
.br
.nm xxx 3 2
.ll -\w'0'u
This test shows how line numbering works with groff.
.nn 2
This test shows how line numbering works with groff.

The result is as follows.

 This  test shows how
 line numbering works
 999 with   groff.   This
1000 test shows how  line
1001 numbering works with
1002 groff.
      This test shows how
      line      numbering
 works  with  groff.
 This test shows how
1005  line      numbering
      works with groff.
Request: .nn [skip]
Register: \n[.nn]

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 2
  .is-numbered
  .is-numbered
  .is-numbered
  .nm
  .is-numbered

The output lines correctly report their numbering status.

  Test line numbering.  This line ISN'T numbered.
  This line ISN'T numbered.
  This line ISN'T numbered.
    1 This line IS numbered.
  This line ISN'T numbered.
Request: .mc glyph [dist]

Print a margin character to the right of the text.92 The first argument is the glyph to be printed. The second argument is the distance away from the right margin. If missing, the previously set value is used; the default is 10 points. For text lines that are too long (that is, longer than the text length plus dist), the margin character is directly appended to the lines.

With no arguments the margin character is turned off. If this occurs before a break, no margin character is printed.

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. Thus

.ll 1i
.mc \[br]
.mc
xxx
.br
xxx

produces

xxx        |
xxx

For empty lines and lines produced by the tl request no margin character is emitted.

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

This is quite useful for indicating text that has changed, and, in fact, there are programs available for doing this (they are called nrchbar and changebar and can be found in any ‘comp.sources.unix’ archive).

.ll 3i
.mc |
This paragraph is highlighted with a margin
character.
.sp
Vertical space isn't marked.
.br
\&
.br
But we can fake it with `\&'.

Result:

This  paragraph is highlighted |
with a margin character.       |

Vertical space isn't marked.   |
                               |
But we can fake it with `\&'.  |
Request: .psbb filename
Register: \n[llx]
Register: \n[lly]
Register: \n[urx]
Register: \n[ury]

Retrieve the bounding box of the PostScript image found in filename. The file must conform to Adobe’s Document Structuring Conventions (DSC); the command searches for a %%BoundingBox comment and extracts the bounding box values into the registers llx, lly, urx, and ury. If an error occurs (for example, psbb cannot find the %%BoundingBox comment), it sets the four registers to zero.

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