Footnotes (The GNU troff Manual)

(23)

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.

(24)

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.

(25)

TeX treats ‘:’ as ending a sentence for spacing purposes. roff formatters do not.

(26)

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.

(27)

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

(28)

See text lines. AT&T troff also cancels end-of-sentence detection.

(29)

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

(30)

The backspace character is also meaningful. See Page Motions.

(31)

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

(32)

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

(33)

Some escape sequences undergo interpolation as well.

(34)

GNU troff offers additional ones. See Writing Macros.

(35)

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

(36)

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

(37)

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

(38)

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 an output comparison expression 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.

(39)

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

(40)

See Font Mounting Positions.

(41)

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.

(42)

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

(46)

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

(47)

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

(48)

See Line Layout and Manipulating Type Size and Vertical Spacing.

(49)

See Traps.

(50)

See Registers.

(51)

See Numeric Expressions.

(52)

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

(53)

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

(54)

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

(55)

(56)

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

(57)

(58)

See Setting Registers, for examples.

(59)

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.

(60)

See Diversions.

(61)

See Page Motions.

(62)

See Delimiters.

(63)

(64)

See Assigning Register Formats.

(65)

See Invoking Requests and Conditionals and Loops.

(66)

See Setting Registers.

(67)

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.

(68)

See Delimiters.

(69)

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

(70)

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

(71)

(72)

See Manipulating Filling and Adjustment.

(73)

(74)

(75)

See Strings.

(76)

See Strings.

(77)

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

(78)

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

(79)

Plan 9 troff does.

(80)

See Page Layout.

(81)

See Strings.

(82)

See Blank Line Traps.

(83)

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

(84)

See Writing Macros.

(85)

\~ is fairly portable; see Other Differences.

(86)

(87)

See Using Escape Sequences.

(88)

See Copy Mode.

(89)

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.

(90)

(91)

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

(92)

See Copy Mode.

(93)

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

(94)

See Copy Mode.

(95)

See Copy Mode.

(96)

TeX does have such a mechanism.

(97)

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

(98)

See Page Layout.

(99)

See Operators in Conditionals.

(100)

See Implementation Differences.

(101)

This claim may be more aspirational than descriptive.

(102)

See Copy Mode.

(103)

except in copy mode on Plan 9 troff

(104)

See Copy Mode.

(105)

See Copy Mode.

(106)

See Conditional Blocks.

(107)

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

(108)

See Auto-increment.

(109)

(110)

See Page Motions.

(111)

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

(112)

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

(113)

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

(114)

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

(115)

See Copy Mode.

(116)

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

(117)

In compatibility mode, GNU troff uses ‘w’ and ‘z’ to represent 5,000 and 10,000 in Roman numerals, respectively, following the convention of AT&T troff, and increasing the representable range of register values to Arabic ±39,999. Following Unicode’s recommendation, GNU troff outputs Roman numerals using only alphabetic characters, not Roman numeral characters from Unicode’s Number Forms block.

(118)

See Copy Mode.

(119)

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

(120)

(121)

See Manipulating Hyphenation.

(122)

This test does not work with AT&T troff, which generates device-independent output even when it does not need to.

(123)

See Debugging.

(124)

See Line Continuation.

(125)

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

(126)

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

(127)

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

(128)

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.

(129)

GNU troff retains those supplied by hyphenation pattern exception files; see below.

(130)

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

(131)

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

(132)

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.

(133)

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.

(134)

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

(135)

(136)

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

(137)

See the discussion of the ds request in Strings.

(138)

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

(139)

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

(140)

(141)

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.

(142)

See Page Control and Other Differences.

(143)

See Drawing Geometric Objects.

(144)

or geometric objects; see Drawing Geometric Objects

(145)

to the top-level diversion; see Diversions

(146)

DWB 3.3, Plan 9, and Heirloom Doctools troffs uses the register .S for this purpose, lack, and thus do not report, GNU troff’s T extension to tab stop syntax.

(147)

See Copy Mode.

(148)

(149)

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.

(150)

See GNU troff Internals, for more on this process.

(151)

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

(152)

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

(153)

(154)

(155)

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

(156)

(157)

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

(158)

(159)

See Copy Mode.

(160)

See Environments. 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.

(161)

See Diversions.

(162)

See Diversions, for a comparison of nl with the .h and .d registers.

(163)

(164)

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.

(165)

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

(166)

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.

(167)

See Font Description File Format.

(168)

See DESC File Format.

(169)

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

(170)

(171)

(172)

See Debugging.

(173)

(174)

See DESC File Format.

(175)

(176)

(177)

(178)

(179)

(180)

See Debugging.

(181)

GNU troff looks up fonts by name with a search that is O(n) in the length n of the dynamically sized mounting position list.

(182)

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

(183)

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

(184)

See Strings.

(185)

(186)

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

(187)

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

(188)

GNU troff emits a warning in category ‘char’. Plan 9 troff, uniquely, formats name as text.

(189)

See Debugging.

(190)

See Character Classes.

(191)

This is the same as having a zero space factor in TeX.

(192)

See Copy Mode.

(193)

(194)

See Character Classes.

(195)

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

(196)

See Font Description File Format.

(197)

(198)

(199)

(200)

(201)

(202)

(203)

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

(204)

See Font Description File Format.

(205)

(206)

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.

(207)

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.

(208)

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

(209)

(210)

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

(211)

See Using Fractional Type Sizes.

(212)

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

(213)

(214)

(215)

The output device’s DESC file specifies which type sizes are normally allowed; see DESC File Format.

(216)

See Using Fractional Type Sizes.

(217)

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

(218)

See Diversions.

(219)

See Vertical Position Traps.

(220)

See The Implicit Page Trap.

(221)

(222)

See Diversions.

(223)

(224)

(225)

(226)

See Debugging.

(227)

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

(228)

(229)

(230)

(231)

(232)

(233)

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

(234)

See Copy Mode.

(235)

See Parameters.

(236)

See Diversions.

(237)

See Punning Names.

(238)

See Writing Macros.

(239)

(240)

See Copy Mode.

(241)

See Punning Names.

(242)

See Debugging.

(243)

See GNU troff Internals, for details of nodes inserted automatically by GNU troff.

(244)

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

(245)

See groff_char(7).

(246)

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

(247)

See Writing Macros.

(248)

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.

(249)

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.

(250)

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

(251)

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

(252)

See Copy Mode.

(253)

This bizarre behavior maintains compatibility with AT&T troff.

(254)

When its parser can tell that a brace escape sequence is useless, GNU troff emits a warning in category ‘style’. See Warnings.

(255)

See while.

(256)

See Copy Mode.

(257)

unless you redefine it

(258)

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

(259)

See Copy Mode.

(260)

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.

(261)

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

(262)

as trace.tmac does

(263)

See Copy Mode.

(264)

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.

(265)

See Punning Names.

(266)

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

(267)

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

(268)

(269)

See Traps.

(270)

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, as configured by ‘.vs .5i’ for example, make it obvious.

(271)

(272)

(273)

(274)

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.

(275)

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

(276)

DWB and Heirloom Doctools troffs do neither.

(277)

See The Implicit Page Trap.

(278)

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

(279)

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.

(280)

See Debugging.

(281)

See Diversions.

(282)

See Debugging.

(283)

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

(284)

(285)

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

(286)

(287)

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

(288)

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

(289)

See Postprocessor Access.

(290)

We must double the backslash. Recall Copy Mode.

(291)

See Debugging.

(292)

This quantity is also known as the advance width; recall the cs request description in Artificial Fonts.

(293)

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

(294)

See GNU troff Output.

(295)

(296)

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.

(297)

See Debugging.

(298)

See GNU troff Output.

(299)