Footnotes (The GNU troff Manual)

Footnotes

Besides groff, neatroff is an exception.

(3)

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

(5)

roff is the language of historical Unix manuals, and of man pages to this day.

(6)

POSIX has not standardized a mechanism for the man command to distinguish pages by numeric category. If ‘man 'groff(7)'’ produces an error, attempt ‘man 7 groff’ or ‘man -s 7 groff’.

(7)

GNU troff does not, however, accept newlines (line feeds) in file names supplied as arguments to requests.

(8)

The mso request loads a macro file of any name. See Host System Service Access.

(10)

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.

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.

(12)

defined in ms Footnotes

(13)

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

(14)

This idiosyncrasy arose through feature accretion; for example, the B macro in Sixth Edition 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.

(15)

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

(16)

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

(17)

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

(18)

(19)

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. In groff ms, the PN and % registers are aliases.

(20)

Removal beforehand is necessary because groff ms aliases these macros with a diagnostic one; you want to reorient the aliased name before (re-)populating the macro.

(21)

See Device and Font Description Files.

(22)

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.

(23)

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.

(24)

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.

(25)

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

(26)

See text lines.

(27)

“Tab” abbreviates “tabulation”, suggesting a table arrangement mechanism.

(28)

The backspace character is also meaningful; see Page Motions.

(29)

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

(30)

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

(31)

Some escape sequences undergo interpolation as well.

(32)

GNU troff offers additional ones. See Writing Macros.

(33)

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

(34)

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

(35)

It also emits a warning in category ‘input’. See Warnings.

(36)

Historically, control characters like ASCII STX, ETX, and BEL (Control+B, Control+C, and Control+G, respectively) 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 the program parses delimited arguments at a different input level than their surrounding context. See Implementation Differences.

(37)

KOI8-R code points in the range 0x80–0x9F are not valid input to GNU troff; recall Input Format. This restriction should be no impediment to practical documents, as these KOI8-R code points do not encode letters, but box-drawing symbols and characters that are better obtained via special character escape sequences; see groff_char(7).

(38)

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.

(39)

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

(40)

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

(41)

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

(42)

See Registers.

(43)

See Numeric Expressions.

(44)

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

(45)

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

(46)

If overflow would occur, GNU troff emits a warning in category ‘range’. See Warnings.

(47)

GNU troff emits a warning in category ‘number’. See Warnings.

(48)

See Conditionals and Loops.

(49)

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.

(50)

See Diversions.

(51)

Use of escape sequences in identifiers is not portable. For example, DWB 3.3 troff accepts \_. Plan 9 troff does too, along with \', \`, and \-. Solaris troff rejects all of these except \_, but accepts \&, \{, \}, \SPC, \%, and \c. Heirloom Doctools troff rejects all of these, including \_, but accepts \!, which the others reject. GNU troff rejects all of the foregoing.

(52)

GNU troff emits a warning in category ‘mac’. See Warnings.

(53)

GNU troff emits a warning in category ‘reg’. See Warnings.

(54)

Recall Identifiers.

(55)

In compatibility mode, a space is not necessary after a request or macro name of two characters’ length.

(56)

Plan 9 troff does.

(57)

GNU troff emits a warning in category ‘mac’. See Warnings.

(58)

\~ is fairly portable; see Other Differences.

(59)

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.

(60)

GNU troff emits a warning in category ‘escape’. See Warnings.

(61)

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

(62)

TeX does have such a mechanism.

(63)

The GNU eqn(1) and tbl(1) preprocessors use parameterized but non-delimited special character escape sequences \( and \[ to bracket portions of their output.

(67)

This claim may be more aspirational than descriptive.

(68)

except in copy mode on Plan 9 troff

(69)

See Copy Mode.

(70)

See Conditional Blocks.

(71)

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

(72)

See Page Motions.

(73)

GNU troff emits a warning in category ‘reg’. See Warnings.

(74)

GNU troff emits a warning in category ‘reg’. See Warnings.

(75)

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

(76)

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

(77)

See Environments.

(78)

See Manipulating Hyphenation.

(79)

though not necessarily to the output device; see Diversions

(80)

If you’re not sure whether an input line has been productive, you can use the pline request before and after it to see whether it produced any output nodes. See Debugging.

(81)

See Line Continuation.

(82)

The .R register interpolates the largest value that GNU troff can work with. Recall Built-in Registers.

(83)

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

(84)

See Font Description File Format. This request is incorrectly documented in the AT&T troff manual as using units of 1/36 em.

(85)

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.

(86)

GNU troff emits a warning in category ‘missing’. See Warnings.

(87)

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

(88)

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

(89)

The mode is a vector of Boolean values 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.

(90)

The formatter prevents hyphenation if the next page location trap is closer to the vertical drawing position than the next text baseline would be. See Page Location Traps. A macro package might also employ value ‘2’ to prevent hyphenation before a display; recall Displays and Keeps.

(91)

See subsection “Localization packages” of groff_tmac(5).

(92)

See Environments.

(93)

For more detail on localization, see groff_tmac(5).

(94)

See the discussion of the ds request in Strings.

(95)

GNU troff also emits a warning in category ‘range’. See Warnings.

(96)

GNU troff also emits a warning in category ‘range’. See Warnings.

(97)

See Page Location Traps.

(98)

To shift the text baseline for part of an output line—to set super- or subscripts, for instance–use the \v escape sequence. See Page Motions.

(99)

See Drawing Geometric Objects.

(100)

or geometric objects; see Drawing Geometric Objects

(101)

to the top-level diversion; see Diversions

(102)

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

(103)

Pronounce “leader” to rhyme with “feeder”; it refers to how the glyphs “lead” the eye across the page to the corresponding page number or other datum.

(104)

A GNU nroff program is available for convenience; it runs GNU troff to perform formatting; see nroff(1).

(105)

See Conditionals and Loops, for more on built-in conditions.

(106)

See Copy Mode.

(107)

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.

(108)

See Diversions.

(109)

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

(110)

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

(111)

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

(112)

See Font Description File Format.

(113)

It also emits a warning in category ‘font’ or ‘range’, as appropriate. See Warnings.

(114)

See DESC File Format.

(115)

Depending on the breadth of the output device’s glyph repertoire, the characters ', -, ^, `, and ~ can be exceptions to this rule. " and \ are not exceptions, but because they are syntactically meaningful to the formatter, access to their glyphs may require use of special characters (or changing or disabling the escape character). See groff_char(7).

(116)

Fonts do not necessarily arrange their glyphs per a standard character encoding.

(117)

See Strings.

(118)

See Device and Font Description Files.

(119)

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

(120)

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

(121)

See Compatibility Mode.

(122)

See Character Classes.

(123)

See GNU troff Internals.

(124)

Mutually recursive character definitions are handled similarly.

(125)

See Font Description File Format.

(126)

See Environments.

(127)

See Miscellaneous.

(128)

See Environments.

(129)

See Miscellaneous.

(130)

A monospaced font may possess glyphs for ligatures, but they nevertheless seldom see use to set text.

(131)

Opinions of this escape sequence’s best name abound. “Zero-width space” is a popular misnomer: roff formatters do not treat it like a space; when filling, they do not break a line where \& appears. 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.

(132)

In text fonts, parentheses are often the tallest glyphs, but a font’s glyphs may not match the nominal type size! In the standard PostScript font families, 10-point Times sets better with 9-point Helvetica and 11-point Courier than if all were used at 10 points. Recall the fzoom request in Selecting Fonts for a remedy.

(133)

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

(134)

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

(135)

In compatibility mode only, a non-zero n must be in the range 4–39. See Compatibility Mode.

(136)

See Device and Font Description Files.

(137)

These are known vulgarly as “ANSI” colors, after its X3.64 standard, now withdrawn.

(138)

See Copy Mode.

(139)

GNU troff emits a warning in category ‘mac’. See Warnings.

(140)

We refer to vtroff, which converted the C/A/T command stream produced by early-vintage AT&T troff to input suitable for Versatec and Benson-Varian plotters.

(141)

Strictly, letters not otherwise recognized are treated as output comparison delimiters. A portable document avoids 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.

(142)

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

(143)

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

(144)

See Copy Mode.

(145)

This bizarre behavior maintains compatibility with AT&T troff.

(146)

See while.

(147)

See Copy Mode.

(148)

unless you redefine it

(149)

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

(150)

See Copy Mode.

(151)

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.

(152)

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

(153)

as trace.tmac does

(154)

See Copy Mode.

(155)

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.

(156)

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

(157)

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

(158)

See Page Location Traps.

(159)

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.

(160)

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.

(161)

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

(162)

See The Implicit Page Trap.

(163)

A trap planted at ‘20i’ or ‘-30i’ cannot spring on a page of length ‘11i’.

(164)

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.

(165)

See Debugging.

(166)

See Diversions.

(167)

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

(168)

See GNU troff Internals.

(169)

GNU troff emits a warning in category ‘mac’. See Warnings.

(170)

See Environments.

(171)

GNU troff emits a warning in category ‘di’. See Warnings.

(172)

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

(173)

We must double the backslash. Recall Copy Mode.

(174)

See Debugging.

(175)

GNU troff emits a warning in category ‘file’. See Warnings.

(176)

See GNU troff Internals.

(177)

POSIX command environments and roff formatters employ different integer-to-Boolean interpretation conventions; a POSIX command exits with a zero status if it succeeds and a positive one if it fails, whereas a roff register tests “true” if it has a positive value.

(178)

See Debugging.

(179)

See GNU troff Output.

(180)

See GNU troff Internals.

(181)

When encountered, these produce warnings in category ‘char’. See Warnings.

(182)

See Device Control Commands.

(183)

When not in copy mode, the formatter does not tokenize the escape sequences \f, \F, \H, \m, \M, \R, \s, and \S, but instead updates the environment.

(184)

GNU troff encodes tokens that aren’t Unicode Basic Latin characters as code points in the C0 and C1 control ranges; we plan to move them to the Unicode Private Use Area (PUA) or to code points outside the Unicode encoding space in a future release.

(185)

Because GNU troff’s internals are subject to revision, we do not show the output of these examples. The names and structures of node types may change over time. The JSON interpreter jq(1) is not essential, but can be helpful in understanding the topology of the node trees populating output lines and diversions in particular.

(186)

You may wonder why a glyph node for ‘hy’ exists when this example doesn’t produce one on the output. That’s because the break is discretionary; at the time a word is formatted into nodes, GNU troff doesn’t know where the output line will break. Later, when processesing a pending output line, GNU troff has that knowledge, and iterates through the output line’s node list, using its discretion to discard these hyphen glyph nodes everywhere except when hyphenating a word at the end of the line.

(187)

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

(188)

Recall Strings.

(189)

Thus,

.ll 10n
\%antidisestablishmen\%tarianism
.br
\&\%antidisestablishmen\%tarianism
.pl \n(nlu

produces different results with each of the three formatters.