Footnotes (The GNU Troff Manual)

#### Footnotes

##### (1)

The ‘`g`’ prefix is not used on all systems; see Invoking `groff`.

##### (2)

Unix and related operating systems distinguish standard output and standard error streams because of `troff`: https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html.

##### (3)

See Line Layout.

##### (4)

Besides `groff`, `neatroff` is an exception.

##### (5)

The `mso` request does not have these limitations. See I/O.

##### (6)

The remainder of this chapter is based on Writing Papers with nroff using -me by Eric P. Allman, which is distributed with `groff` as `meintro.me`.

##### (7)

While manual pages are older, early ones used macros supplanted by the `man` package of Seventh Edition Unix (1979). `ms` shipped with Sixth Edition (1975) and was documented by Mike Lesk in a Bell Labs internal memorandum.

##### (8)

defined in Footnotes

##### (9)

Distinguish a document title from “titles”, which are what `roff` systems call headers and footers collectively.

##### (10)

This idiosyncrasy arose through feature accretion; for example, the `B` macro in Version 6 Unix `ms` (1975) accepted only one argument, the text to be set in boldface. By Version 7 (1979) it recognized a second argument; in 1990, `groff` `ms` added a “pre” argument, placing it third to avoid breaking support for older documents.

##### (11)

“Portable Document Format Publishing with GNU Troff”, `pdfmark.ms` in the `groff` distribution, uses this technique.

##### (12)

Unix Version 7 `ms`, its descendants, and GNU `ms` prior to `groff` version 1.23.0

##### (13)

You could reset it after each call to `.1C`, `.2C`, or `.MC`.

##### (14)

Typing Documents on the UNIX System: Using the -ms Macros with Troff and Nroff, M. E. Lesk, Bell Laboratories, 1978

##### (15)

Register values are converted to and stored as basic units. See Measurements.

##### (16)

If you redefine the `ms` `PT` macro and desire special treatment of certain page numbers (like ‘`1`’), you may need to handle a non-Arabic page number format, as `groff` `ms`’s `PT` does; see the macro package source. `groff` `ms` aliases the `PN` register to `%`.

##### (17)

The removal beforehand is necessary because `groff` `ms` aliases these macros to a diagnostic macro, and you want to redefine the aliased name, not its target.

##### (18)

See Device and Font Description Files.

##### (19)

Tabs and leaders also separate words. Escape sequences can function as word characters, word separators, or neither—the last simply have no effect on GNU `troff`’s idea of whether an input character is within a word. We’ll discuss all of these in due course.

##### (20)

A well-researched jeremiad appreciated by `groff` contributors on both sides of the sentence-spacing debate can be found at https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324.

##### (21)

This statement oversimplifies; there are escape sequences whose purpose is precisely to produce glyphs on the output device, and input characters that aren’t part of escape sequences can undergo a great deal of processing before getting to the output.

##### (22)

The mnemonics for the special characters shown here are “dagger”, “double dagger”, “right (double) quote”, and “closing (single) quote”. See the groff_char(7) man page.

##### (23)

“Text lines” are defined in Requests and Macros.

##### (24)

“Tab” is short for “tabulation”, revealing the term’s origin as a spacing mechanism for table arrangement.

##### (25)

The `\`RET`` escape sequence can alter how an input line is classified; see Line Continuation.

##### (26)

Argument handling in macros is more flexible but also more complex. See Calling Macros.

##### (27)

Some escape sequences undergo interpolation as well.

##### (28)

GNU `troff` offers additional ones. See Writing Macros.

##### (29)

Macro files and packages frequently define registers and strings as well.

##### (30)

The semantics of certain punctuation code points have gotten stricter with the successive standards, a cause of some frustration among man page writers; see the groff_char(7) man page.

##### (31)

The DVI output device defaults to using the Computer Modern (CM) fonts; `ec.tmac` loads the EC fonts instead, which provide Euro ‘`\[Eu]`’ and per mille ‘`\[%0]`’ glyphs.

##### (32)

Emacs: `fill-column: 72`; Vim: `textwidth=72`

##### (33)

`groff` does not yet support right-to-left scripts.

##### (34)

`groff`’s terminal output devices have page offsets of zero.

##### (35)

Provision is made for interpreting and reporting decimal fractions in certain cases.

##### (36)

If that’s not enough, see the groff_tmac(5) man page for the `62bit.tmac` macro package.

##### (37)

See Conditionals and Loops.

##### (38)

Control structure syntax creates an exception to this rule, but is designed to remain useful: recalling our example, ‘`.if 1 .Underline this`’ would underline only “this”, precisely. See Conditionals and Loops.

##### (39)

See Diversions.

##### (40)

Historically, control characters like ASCII STX, ETX, and BEL (`Control+B`, `Control+C`, and `Control+G`) have been observed in `roff` documents, particularly in macro packages employing them as delimiters with the output comparison operator to try to avoid collisions with the content of arbitrary user-supplied parameters (see Operators in Conditionals). We discourage this expedient; in GNU `troff` it is unnecessary (outside of compatibility mode) because delimited arguments are parsed at a different input level than the surrounding context. See Implementation Differences.

##### (41)

Consider what happens when a C1 control `0x80`–`0x9F` is necessary as a continuation byte in a UTF-8 sequence.

##### (42)

Recall Identifiers.

##### (43)

In compatibility mode, a space is not necessary after a request or macro name of two characters’ length. Also, Plan 9 `troff` allows tabs to separate arguments.

##### (44)

`\~` is fairly portable; see Other Differences.

##### (45)

Strictly, you can neglect to close the last quoted macro argument, relying on the end of the control line to do so. We consider this lethargic practice poor style.

##### (46)

The omission of spaces before the comment escape sequences is necessary; see Strings.

##### (47)

TeX does have such a mechanism.

##### (48)

This claim may be more aspirational than descriptive.

##### (49)

See Conditional Blocks.

##### (50)

Exception: auto-incrementing registers defined outside the ignored region will be modified if interpolated with `\n±` inside it. See Auto-increment.

##### (51)

A negative auto-increment can be considered an “auto-decrement”.

##### (52)

GNU `troff` dynamically allocates memory for as many registers as required.

##### (53)

unless diverted; see Diversions

##### (54)

See Line Continuation.

##### (55)

Recall Filling and Sentences for the definitions of word and sentence boundaries, respectively.

##### (56)

Whether a perfect algorithm for this application is even possible is an unsolved problem in computer science: https://tug.org/docs/liang/liang-thesis.pdf.

##### (57)

`\%` itself stops marking hyphenation points but still produces no output glyph.

##### (58)

“Soft” because it appears in output only where a hyphenation break is performed; a “hard” hyphen, as in “long-term”, always appears.

##### (59)

The mode is a vector of Booleans encoded as an integer. To a programmer, this fact is easily deduced from the exclusive use of powers of two for the configuration parameters; they are computationally easy to “mask off” and compare to zero. To almost everyone else, the arrangement seems recondite and unfriendly.

##### (60)

Hyphenation is prevented if the next page location trap is closer to the vertical drawing position than the next text baseline would be. See Page Location Traps.

##### (61)

For more on localization, see the groff_tmac(5) man page.

##### (62)

See Page Location Traps.

##### (63)

See Drawing Geometric Objects.

##### (64)

or geometric objects; see Drawing Geometric Objects

##### (65)

to the top-level diversion; see Diversions

##### (66)

Plan 9 `troff` uses the register `.S` for this purpose.

##### (67)

This is pronounced to rhyme with “feeder”, and refers to how the glyphs “lead” the eye across the page to the corresponding page number or other datum.

##### (68)

A GNU `nroff` program is available for convenience; it calls GNU `troff` to perform the formatting.

##### (69)

Historically, the `\c` escape sequence has proven challenging to characterize. Some sources say it “connects the next input text” (to the input line on which it appears); others describe it as “interrupting” text, on the grounds that a text line is interrupted without breaking, perhaps to inject a request invocation or macro call.

##### (70)

See Traps.

##### (71)

See Diversions.

##### (72)

Terminals and some output devices have fonts that render at only one or two sizes. As examples of the latter, take the `groff` `lj4` device’s Lineprinter, and `lbp`’s Courier and Elite faces.

##### (73)

Font designers prepare families such that the styles share esthetic properties.

##### (74)

Historically, the fonts `troff`s dealt with were not Free Software or, as with the Graphic Systems C/A/T, did not even exist in the digital domain.

##### (75)

See Font Description File Format.

##### (76)

See `DESC` File Format.

##### (77)

Not all versions of the `man` program support the `-T` option; use the subsequent example for an alternative.

##### (78)

This is “Normalization Form D” as documented in Unicode Standard Annex #15 (https://unicode.org/reports/tr15/).

##### (79)

See Compatibility Mode.

##### (80)

Output glyphs don’t—to GNU `troff`, a glyph is simply a box with an index into a font, a given height above and depth below the baseline, and a width.

##### (81)

Opinions of this escape sequence’s name abound. “Zero-width space” is a popular misnomer: `roff` formatters do not treat it like a space. Ossanna called it a “non-printing, zero-width character”, but the character causes output even though it does not “print”. If no output line is pending, the dummy character starts one. Contrast an empty input document with one containing only `\&`. The former produces no output; the latter, a blank page.

##### (82)

In text fonts, the tallest glyphs are typically parentheses. Unfortunately, in many cases the actual dimensions of the glyphs in a font do not closely match its declared type size! For example, in the standard PostScript font families, 10-point Times sets better with 9-point Helvetica and 11-point Courier than if all three were used at 10 points.

##### (83)

Rhyme with “sledding”; mechanical typography used lead metal (Latin plumbum).

##### (84)

The claim appears to have been true of Ossanna `troff` for the C/A/T device; Kernighan made device-independent `troff` more flexible.

##### (85)

See Device and Font Description Files.

##### (86)

also known vulgarly as “ANSI colors”

##### (87)

See Copy Mode.

##### (88)

This refers to `vtroff`, a translator that would convert the C/A/T output from early-vintage AT&T `troff` to a form suitable for Versatec and Benson-Varian plotters.

##### (89)

Strictly, letters not otherwise recognized are treated as output comparison delimiters. For portability, it is wise to avoid using letters not in the list above; for example, Plan 9 `troff` uses ‘`h`’ to test a mode it calls `htmlroff`, and GNU `troff` may provide additional operators in the future.

##### (90)

Because formatting of the comparands takes place in a dummy environment, vertical motions within them cannot spring traps.

##### (91)

All of this is to say that the lists of output nodes created by formatting xxx and yyy must be identical. See `gtroff` Internals.

##### (92)

This bizarre behavior maintains compatibility with AT&T `troff`.

##### (93)

See while.

##### (94)

See Copy Mode.

##### (95)

unless you redefine it

##### (96)

“somewhat less” because things other than macro calls can be on the input stack

##### (97)

See Copy Mode.

##### (98)

While it is possible to define and call a macro ‘`.`’, you can’t use it as an end macro: during a macro definition, ‘`..`’ is never handled as calling ‘`.`’, even if ‘`.de name .`’ explicitly precedes it.

##### (99)

Its structure is adapted from, and isomorphic to, part of a solution by Tadziu Hoffman to the problem of reflowing text multiple times to find an optimal configuration for it. https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html

##### (100)

If they were not, parameter interpolations would be similar to command-line parameters—fixed for the entire duration of a `roff` program’s run. The advantage of interpolating `\$` escape sequences even in copy mode is that they can interpolate different contents from one call to the next, like function parameters in a procedural language. The additional escape character is the price of this power.

##### (101)

Compare this to the `\def` and `\edef` commands in TeX.

##### (102)

These are lightly adapted from the `groff` implementation of the `ms` macros.

##### (103)

At the `grops` defaults of 10-point type on 12-point vertical spacing, the difference between half a vee and half an em can be subtle: large spacings like ‘`.vs .5i`’ make it obvious.

##### (104)

See Strings, for an explanation of the trailing ‘`\"`’.

##### (105)

(hc, vc) is adjusted to the point nearest the perpendicular bisector of the arc’s chord.

##### (106)

See The Implicit Page Trap.

##### (107)

A trap planted at ‘`20i`’ or ‘`-30i`’ will not be sprung on a page of length ‘`11i`’.

##### (108)

It may help to think of each trap location as maintaining a queue; `wh` operates on the head of the queue, and `ch` operates on its tail. Only the trap at the head of the queue is visible.

##### (109)

See Debugging.

##### (110)

See Diversions.

##### (111)

While processing an end-of-input macro, the formatter assumes that the next page break must be the last; it goes into “sudden death overtime”.

##### (112)

Another, taken by the `groff` `man` macros, is to intercept `ne` requests and wrap `bp` ones.

##### (113)

Thus, the “water” gets “higher” proceeding down the page.

##### (114)

The backslash is doubled. See Copy Mode.

##### (115)

that is, ISO 646:1991-IRV or, popularly, “US-ASCII”

##### (116)

They are bypassed because these parameters are not rendered as glyphs in the output; instead, they remain abstract characters—in a PDF bookmark or a URL, for example.

##### (117)

Recall Line Layout.

##### (118)

Historically, tools named `nrchbar` and `changebar` were developed for marking changes with margin characters and could be found in archives of the `comp.sources.unix` USENET group. Some proprietary Unices also offer(ed) a `diffmk` program.

##### (119)

Except the escape sequences `\f`, `\F`, `\H`, `\m`, `\M`, `\R`, `\s`, and `\S`, which are processed immediately if not in copy mode.

##### (120)

The Graphic Systems C/A/T phototypesetter (the original device target for AT&T `troff`) supported only a few discrete type sizes in the range 6–36 points, so Ossanna contrived a special case in the parser to do what the user must have meant. Kernighan warned of this in the 1992 revision of CSTR #54 (§2.3), and more recently, McIlroy referred to it as a “living fossil”.

##### (121)

DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 `troff` all support it.

##### (122)

Naturally, if you’ve changed the escape character, you need to prefix the `e` with whatever it is—and you’ll likely get something other than a backslash in the output.

##### (123)

The `rs` special character identifier was not defined in AT&T `troff`’s font description files, but is in those of its lineal descendant, Heirloom Doctools `troff`, as of the latter’s 060716 release (July 2006).

##### (124)

The parser and postprocessor for intermediate output can be found in the file
`groff-source-dir/src/libs/libdriver/input.cpp`.

##### (125)

Plan 9 `troff` has also abandoned the binary format.

##### (126)

800-point type is not practical for most purposes, but using it enables the quantities in the font description files to be expressed as integers.

##### (127)

`groff` requests and escape sequences interpret non-negative font names as mounting positions instead. Further, a font named ‘`0`’ cannot be automatically mounted by the `fonts` directive of a `DESC` file.

##### (128)

For typesetter devices, this directive is misnamed since it starts a list of glyphs, not characters.

##### (129)

that is, any integer parsable by the C standard library’s strtol(3) function