Debian Codegraph @

upstream/debian-trixie/man7/roff.7

raw
1 '\" t
2 .TH roff 7 "3 June 2025" "groff 1.23.0"
3 .SH Name
4 roff \- concepts and history of
5 .I roff
6 typesetting
7 .
8 .
9 .\" TODO: Synchronize this material with introductory section(s) of our
10 .\" Texinfo manual, and then keep it that way.
11 .
12 .\" ====================================================================
13 .\" Legal Terms
14 .\" ====================================================================
15 .\"
16 .\" Copyright (C) 2000-2023 Free Software Foundation, Inc.
17 .\"
18 .\" This file is part of groff, the GNU roff type-setting system.
19 .\"
20 .\" Permission is granted to copy, distribute and/or modify this
21 .\" document under the terms of the GNU Free Documentation License,
22 .\" Version 1.3 or any later version published by the Free Software
23 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
24 .\" and with no Back-Cover Texts.
25 .\"
26 .\" A copy of the Free Documentation License is included as a file
27 .\" called FDL in the main directory of the groff source package.
28 .\"
29 .\" A copy of the GNU Free Documentation License is also available in this
30 .\" Debian package as /usr/share/doc/groff/copyright.
31 .
32 .
33 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
34 .do nr *groff_roff_7_man_C \n[.cp]
35 .cp 0
36 .
37 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
38 .nr do-fallback 0
39 .if !\n(.f .nr do-fallback 1 \" mandoc
40 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
41 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
42 .if \n[do-fallback] \{\
43 . de MR
44 . ie \\n(.$=1 \
45 . I \%\\$1
46 . el \
47 . IR \%\\$1 (\\$2)\\$3
48 . .
49 .\}
50 .rr do-fallback
51 .
52 .
53 .\" ====================================================================
54 .SH Description
55 .\" ====================================================================
56 .
57 The term
58 .I roff
59 denotes a family of document formatting systems known by names like
60 .IR troff ,
61 .IR nroff ,
62 and
63 .IR ditroff .
64 .
65 A
66 .I roff
67 system consists of an interpreter for an extensible text formatting
68 language and a set of programs for preparing output for various devices
69 and file formats.
70 .
71 Unix-like operating systems often distribute a
72 .I roff
73 system.
74 .
75 The manual pages on Unix systems
76 (\[lq]man\~pages\[rq])
77 and bestselling books on software engineering,
78 including Brian Kernighan and Dennis Ritchie's
79 .I The C Programming Language
80 and W.\& Richard Stevens's
81 .I Advanced Programming in the Unix Environment
82 have been written using
83 .I roff
84 systems.
85 .
86 GNU
87 .IR roff \[em] groff \[em]is
88 arguably the most widespread
89 .I roff
90 implementation.
91 .
92 .
93 .P
94 Below we present
95 typographical concepts that form the background of all
96 .I roff
97 implementations,
98 narrate the development history of some
99 .I roff
100 systems,
101 detail the command pipeline managed by
102 .MR groff 1 ,
103 survey the formatting language,
104 suggest tips for editing
105 .I roff
106 input,
107 and recommend further reading materials.
108 .
109 .
110 .\" ====================================================================
111 .SH Concepts
112 .\" ====================================================================
113 .
114 .\" BEGIN Keep roughly parallel with groff.texi nodes "Text" through
115 .\" "Tab Stops".
116 .I roff
117 input files contain text interspersed with instructions to control the
118 formatter.
119 .
120 Even in the absence of such instructions,
121 a
122 .I roff
123 formatter still processes its input in several ways,
124 by filling,
125 hyphenating,
126 breaking,
127 and adjusting it,
128 and supplementing it with inter-sentence space.
129 .
130 These processes are basic to typesetting,
131 and can be controlled at the input document's discretion.
132 .
133 .
134 .P
135 When a device-independent
136 .I roff
137 formatter starts up,
138 it obtains information about the device for which it is preparing
139 output from the latter's description file
140 (see
141 .MR groff_font 5 ).
142 .
143 An essential property is the length of the output line,
144 such as \[lq]6.5 inches\[rq].
145 .
146 .
147 .P
148 The formatter interprets plain text files employing the Unix line-ending
149 convention.
150 .
151 It reads input a character at a time,
152 collecting words as it goes,
153 and fits as many words together on an output line as it can\[em]this
154 is known as
155 .I filling.
156 .
157 To a
158 .I roff
159 system,
160 a
161 .I word
162 is any sequence of one or more characters that aren't spaces or
163 newlines.
164 .
165 The exceptions separate words.
166 .
167 .
168 .P
169 A
170 .I roff
171 formatter attempts to detect boundaries between sentences,
172 and supplies additional inter-sentence space between them.
173 .
174 It flags certain characters
175 (normally
176 .RB \[lq] !\& \[rq],
177 .RB \[lq] ?\& \[rq],
178 and
179 .RB \[lq] .\& \[rq])
180 as potentially ending a sentence.
181 .
182 When the formatter encounters one of these
183 .I end-of-sentence characters
184 at the end of an input line,
185 or one of them is followed by two (unescaped) spaces on the same input
186 line,
187 it appends an inter-word space
188 followed by an inter-sentence space in the output.
189 .
190 The dummy character escape sequence
191 .B \[rs]&
192 can be used after an end-of-sentence character to defeat end-of-sentence
193 detection on a per-instance basis.
194 .
195 Normally,
196 the occurrence of a visible non-end-of-sentence character
197 (as opposed to a space or tab)
198 immediately after an end-of-sentence
199 character cancels detection of the end of a sentence.
200 .
201 However,
202 several characters are treated
203 .I transparently
204 after the occurrence of an end-of-sentence character.
205 .
206 That is,
207 a
208 .I roff
209 does not cancel end-of-sentence detection when it processes them.
210 .
211 This is because such characters are often used as footnote markers or to
212 close quotations and parentheticals.
213 .
214 The default set is
215 .BR \[dq] ,
216 .BR \[aq] ,
217 .BR ) ,
218 .BR ] ,
219 .BR * ,
220 .BR \[rs][dg] ,
221 .BR \[rs][dd] ,
222 .BR \[rs][rq] ,
223 and
224 .BR \[rs][cq] .
225 .
226 The last four are examples of
227 .I special characters,
228 escape sequences whose purpose is to obtain glyphs that are not easily
229 typed at the keyboard,
230 or which have special meaning to the formatter
231 (like
232 .BR \[rs] ).
233 .\" slack wording: itself).
234 .
235 .
236 .P
237 When an output line is nearly full,
238 it is uncommon for the next word collected from the input to exactly
239 fill it\[em]typically,
240 there is room left over only for part of the next word.
241 .
242 The process of splitting a word so that it appears partially on one line
243 (with a hyphen to indicate to the reader that the word has been broken)
244 with its remainder on the next is
245 .I hyphenation.
246 .
247 Hyphenation points can be manually specified;
248 .I groff
249 also uses a hyphenation algorithm and language-specific pattern files to
250 decide which words can be hyphenated and where.
251 .
252 Hyphenation does not always occur even when the hyphenation rules for a
253 word allow it;
254 it can be disabled,
255 and when not disabled there are several parameters that can prevent it
256 in certain circumstances.
257 .
258 .
259 .P
260 Once an output line is full,
261 the next word
262 (or remainder of a hyphenated one)
263 is placed on a different output line;
264 this is called a
265 .I break.
266 .
267 In this document and in
268 .I roff
269 discussions generally,
270 a \[lq]break\[rq] if not further qualified always refers to the
271 termination of an output line.
272 .
273 When the formatter is filling text,
274 it introduces breaks automatically to keep output lines from exceeding
275 the configured line length.
276 .
277 After an automatic break,
278 a
279 .I roff
280 formatter
281 .I adjusts
282 the line if applicable
283 (see below),
284 and then resumes collecting and filling text on the next output line.
285 .
286 .
287 .br
288 .ne 2v
289 .P
290 Sometimes,
291 a line cannot be broken automatically.
292 .
293 This usually does not happen with natural language text unless the
294 output line length has been manipulated to be extremely short,
295 but it can with specialized text like program source code.
296 .
297 .I groff
298 provides a means of telling the formatter where the line may be broken
299 without hyphens.
300 .
301 This is done with the non-printing break point escape sequence
302 .BR \[rs]: .
303 .
304 .
305 .P
306 .\" What if the document author wants to stop filling lines temporarily,
307 .\" for instance to start a new paragraph? There are several solutions.
308 There are several ways to cause a break at a predictable location.
309 .
310 A blank input line not only causes a break,
311 but by default it also outputs a one-line vertical space
312 (effectively a blank output line).
313 .
314 Macro packages may discourage or disable this \[lq]blank line
315 method\[rq] of paragraphing in favor of their own macros.
316 .
317 A line that begins with one or more spaces causes a break.
318 .
319 The spaces are output at the beginning of the next line without being
320 .I adjusted
321 (see below).
322 .
323 Again,
324 macro packages may provide other methods of producing indented
325 paragraphs.
326 .
327 Trailing spaces on
328 .I text lines
329 (see below)
330 are discarded.
331 .
332 The end of input causes a break.
333 .
334 .
335 .P
336 After the formatter performs an automatic break,
337 it may then
338 .I adjust
339 the line,
340 widening inter-word spaces until the text reaches the right margin.
341 .
342 Extra spaces between words are preserved.
343 .
344 Leading and trailing spaces are handled as noted above.
345 .
346 Text can be aligned to the left or right margin only,
347 or centered,
348 using
349 .I requests.
350 .
351 .
352 .P
353 A
354 .I roff
355 formatter translates horizontal tab characters,
356 also called simply \[lq]tabs\[rq],
357 in the input into movements to the next tab stop.
358 .
359 These tab stops are by default located every half inch measured from the
360 current position on the input line.
361 .
362 With them,
363 simple tables can be made.
364 .
365 However,
366 this method can be deceptive,
367 as the appearance
368 (and width)
369 of the text in an editor and the results from the formatter can vary
370 greatly,
371 particularly when proportional typefaces are used.
372 .
373 A tab character does not cause a break and therefore does not interrupt
374 filling.
375 .
376 The formatter provides facilities for sophisticated table composition;
377 there are many details to track
378 when using the \[lq]tab\[rq] and \[lq]field\[rq] low-level features,
379 so most users turn to the
380 .MR \%tbl 1
381 preprocessor to lay out tables.
382 .\" END Keep roughly parallel with groff.texi nodes "Text" through "Tab
383 .\" Stops".
384 .
385 .
386 .\" ====================================================================
387 .SS "Requests and macros"
388 .\" ====================================================================
389 .
390 .\" BEGIN Keep roughly parallel with groff.texi node "Requests and
391 .\" Macros".
392 .\" We have now encountered almost all of the syntax there is in the
393 .\" @code{roff} language, with an exception already noted in passing.
394 A
395 .I request
396 is an instruction to the formatter that occurs after a
397 .I control character,
398 which is recognized at the beginning of an input line.
399 .
400 The regular control character is a dot
401 .RB \[lq] .\& \[rq].
402 .
403 Its counterpart,
404 the
405 .I no-break control character,
406 a neutral apostrophe
407 .RB \[lq] \|\[aq]\| \[rq],
408 suppresses the break
409 .\" slack wording: that is
410 implied by some requests.
411 .
412 These characters were chosen because it is uncommon for lines of text in
413 natural languages to begin with them.
414 .
415 If you require a formatted period or apostrophe
416 (closing single quotation mark)
417 where
418 .\" GNU @code{troff}
419 the formatter is expecting a control character,
420 prefix the dot or neutral apostrophe with the dummy character escape
421 sequence,
422 .RB \[lq] \[rs]& \[rq].
423 .
424 .
425 .P
426 An input line beginning with a control character is called a
427 .I control line.
428 .
429 Every line of input that is not a control line is a
430 .I text line.
431 .
432 .
433 .P
434 Requests often take
435 .I arguments,
436 words
437 (separated from the request name and each other by spaces)
438 that specify details of the action
439 .\" GNU @code{troff}
440 the formatter is expected to perform.
441 .
442 If a request is meaningless without arguments,
443 it is typically ignored.
444 .
445 .\" TODO: roff(7): We haven't introduced escape sequences yet.
446 .\" GNU @code{troff}'s requests and escape sequences comprise the
447 .\" control language of the formatter.
448 .
449 Of key importance are the requests that define macros.
450 .
451 Macros are invoked like requests,
452 enabling the request repertoire to be extended or overridden.
453 .\" @footnote{Argument handling in macros is more flexible but also more
454 .\" complex. @xref{Calling Macros}.}
455 .
456 .
457 .P
458 A
459 .I macro
460 can be thought of as an abbreviation you can define for a
461 collection of control and text lines.
462 .
463 When the macro is
464 .I called
465 by giving its name after a control character,
466 it is replaced with what it stands for.
467 .
468 The process of textual replacement is known as
469 .I interpolation.
470 .\" @footnote{Some escape sequences undergo interpolation as well.}
471 Interpolations are handled as soon as they are recognized,
472 and once performed,
473 a
474 .I roff
475 formatter scans the replacement for further requests,
476 macro calls,
477 and escape sequences.
478 .
479 .
480 .P
481 In
482 .I roff
483 systems,
484 the
485 .RB \[lq] de \[rq]
486 request defines a macro.
487 .\" @footnote{GNU @code{troff} offers additional ones. @xref{Writing
488 .\" Macros}.}
489 .\" END Keep roughly parallel with groff.texi node "Requests and
490 .\" Macros".
491 .
492 .
493 .\" ====================================================================
494 .SS "Page geometry"
495 .\" ====================================================================
496 .
497 .\" BEGIN Keep parallel with groff.texi node "Page Geometry".
498 .I roff
499 systems format text under certain assumptions about the size of the
500 output medium,
501 or page.
502 .
503 For the formatter to correctly break a line it is filling,
504 it must know the line length,
505 which it derives from the page width.
506 .\" (@pxref{Line Layout}).
507 .
508 For it to decide whether to write an output line to the current page or
509 wait until the next one,
510 it must know the page length.
511 .\" (@pxref{Page Layout}).
512 .
513 .
514 A device's
515 .I resolution
516 converts practical units like inches or centimeters to
517 .I basic units,
518 a convenient length measure for the output device or file format.
519 .
520 The formatter and output driver use basic units to reckon page
521 measurements.
522 .
523 The device description file defines its resolution and page dimensions
524 (see
525 .MR groff_font 5 ).
526 .\" (@pxref{DESC File Format}).
527 .
528 .
529 .P
530 A
531 .I page
532 is a two-dimensional structure upon which a
533 .I roff
534 system imposes a rectangular coordinate system with its upper left
535 corner as the origin.
536 .
537 Coordinate values are in basic units and increase down and to the right.
538 Useful ones are therefore always positive and within numeric ranges
539 corresponding to the page boundaries.
540 .
541 .
542 .P
543 While the formatter
544 (and,
545 later,
546 output driver)
547 is processing a page,
548 it keeps track of its
549 .I drawing position,
550 which is the location at which the next glyph will be written,
551 from which the next motion will be measured,
552 or where a geometric object will commence rendering.
553 .
554 Notionally,
555 glyphs are drawn from the text baseline upward and to the right.
556 .RI ( groff
557 does not yet support right-to-left scripts.)
558 .
559 The
560 .I text baseline
561 is a
562 (usually invisible)
563 line upon which the glyphs of a typeface are aligned.
564 .
565 A glyph therefore \[lq]starts\[rq] at its bottom-left corner.
566 .
567 If drawn at the origin,
568 a typical letter glyph would lie partially or wholly off the page,
569 depending on whether,
570 like \[lq]g\[rq],
571 it features a descender below the baseline.
572 .
573 .
574 .P
575 Such a situation is nearly always undesirable.
576 .
577 It is furthermore conventional not to write or draw at the extreme edges
578 of the page.
579 .
580 Therefore the initial drawing position of a
581 .I roff
582 formatter is not at the origin,
583 but below and to the right of it.
584 .
585 This rightward shift
586 from the left edge is known as the
587 .I page offset.
588 .
589 .RI ( groff 's
590 terminal output devices have page offsets of zero.)
591 .
592 The downward shift leaves room for a text output line.
593 .
594 .
595 .P
596 Text is arranged on a one-dimensional lattice of text baselines from
597 the top to the bottom of the page.
598 .
599 .I Vertical spacing
600 is the distance between adjacent text baselines.
601 .
602 Typographic tradition sets this quantity to 120% of the type size.
603 .
604 The initial vertical drawing position is one unit of vertical spacing
605 below the page top.
606 .
607 Typographers term this unit a
608 .I vee.
609 .
610 .
611 .P
612 Vertical spacing has an impact on page-breaking decisions.
613 .
614 Generally,
615 when a break occurs,
616 the formatter moves the drawing position to the next text baseline
617 automatically.
618 .
619 If the formatter were already writing to the last line that would fit on
620 the page,
621 advancing by one vee would place the next text baseline off the page.
622 .
623 Rather than let that happen,
624 .I roff
625 formatters instruct the output driver to eject the page,
626 start a new one,
627 and again set the drawing position to one vee below the page top;
628 this is a
629 .I page break.
630 .
631 .
632 .P
633 When the last line of input text corresponds to the last output line
634 that fits on the page,
635 the break caused by the end of input will also break the page,
636 producing a useless blank one.
637 .
638 Macro packages keep users from having
639 to confront this difficulty by setting \[lq]traps\[rq];
640 .\" (@pxref{Traps});
641 moreover,
642 all but the simplest page layouts tend to have headers and footers,
643 or at least bear vertical margins larger than one vee.
644 .\" END Keep parallel with groff.texi node "Page Geometry".
645 .
646 .
647 .\" ====================================================================
648 .SS "Other language elements"
649 .\" ====================================================================
650 .
651 .I Escape sequences
652 start with the
653 .I escape character,
654 a backslash
655 .BR \[rs] ,
656 and are followed by at least one additional character.
657 .
658 They can appear anywhere in the input.
659 .
660 .
661 .P
662 With requests,
663 the escape and control characters can be changed;
664 further,
665 escape sequence recognition can be turned off and back on.
666 .
667 .
668 .P
669 .I Strings
670 store character sequences.
671 .
672 In
673 .IR groff ,
674 they can be parameterized as macros can.
675 .
676 .
677 .P
678 .I Registers
679 store numerical values,
680 including measurements.
681 .
682 The latter are generally in basic units;
683 .I scaling units
684 can be appended to numeric expressions to clarify their meaning when
685 stored or interpolated.
686 .
687 Some read-only predefined registers interpolate text.
688 .
689 .
690 .P
691 .I Fonts
692 are identified either by a name or by a mounting position
693 (a non-negative number).
694 .
695 Four styles are available on all devices.
696 .
697 .B R
698 is \[lq]roman\[rq]:
699 normal,
700 upright text.
701 .
702 .B B
703 is
704 .BR bold ,
705 an upright typeface with a heavier weight.
706 .
707 .B I
708 is
709 .IR italic ,
710 a face that is oblique on typesetter output devices and usually
711 underlined instead on terminal devices.
712 .
713 .B BI
714 is \f[BI]bold-italic\f[]\/, \" indulging a bit of man(7) evil here
715 combining both of the foregoing style variations.
716 .
717 Typesetting devices group these four styles into
718 .I families
719 of text fonts;
720 they also typically offer one or more
721 .I special
722 fonts that provide unstyled glyphs;
723 see
724 .MR groff_char 7 .
725 .
726 .
727 .P
728 .I groff
729 supports named
730 .I colors
731 for glyph rendering and drawing of geometric objects.
732 .
733 Stroke and fill colors are distinct;
734 the stroke color is used for glyphs.
735 .
736 .
737 .P
738 .I Glyphs
739 are visual representation forms of
740 .I characters.
741 .
742 In
743 .I groff,
744 the distinction between those two elements is not always obvious
745 (and a full discussion is beyond our scope).
746 .
747 In brief,
748 \[lq]A\[rq] is a character when we consider it in the abstract:
749 to make it a glyph,
750 we must select a typeface with which to render it,
751 and determine its type size and color.
752 .
753 The formatting process turns input characters into output glyphs.
754 .
755 A few characters commonly seen on keyboards are treated
756 specially by the
757 .I roff
758 language and may not look correct in output if used unthinkingly;
759 they are
760 the (double) quotation mark
761 .RB ( \|\[dq]\| ),
762 the neutral apostrophe
763 .RB ( \|\[aq]\| ),
764 the minus sign
765 .RB ( \- ),
766 the backslash
767 .RB ( \|\[rs]\| ),
768 the caret or circumflex accent
769 .RB ( \[ha] ),
770 the grave accent
771 .RB ( \|\[ga]\| ),
772 and the tilde
773 .RB ( \[ti] ).
774 .
775 All of these and more can be produced with
776 .I special character
777 escape sequences;
778 see
779 .MR groff_char 7 .
780 .
781 .
782 .P
783 .I groff
784 offers
785 .IR streams ,
786 identifiers for writable files,
787 but for security reasons this feature is disabled by default.
788 .
789 .
790 .\" BEGIN Keep roughly parallel with first paragraphs of groff.texi node
791 .\" "Deferring Output".
792 .P
793 A further few language elements arise as page layouts become more
794 sophisticated and demanding.
795 .
796 .I Environments
797 collect formatting parameters like line length and typeface.
798 .
799 A
800 .I diversion
801 stores formatted output for later use.
802 .
803 A
804 .I trap
805 is a condition on the input or output,
806 tested automatically by the formatter,
807 that is associated with a macro,
808 calling it when that condition is fulfilled.
809 .
810 .
811 .P
812 Footnote support often exercises all three of the foregoing features.
813 .
814 A simple implementation might work as follows.
815 .
816 A pair of macros is defined:
817 one starts a footnote and the other ends it.
818 .
819 The author calls the first macro where a footnote marker is desired.
820 .
821 The macro establishes a diversion so that the footnote text is collected
822 at the place in the body text where its corresponding marker appears.
823 .
824 An environment is created for the footnote so that it is set at a
825 smaller typeface.
826 .
827 The footnote text is formatted in the diversion using that environment,
828 but it does not yet appear in the output.
829 .
830 The document author calls the footnote end macro,
831 which returns to the previous environment and ends the diversion.
832 .
833 Later,
834 after much more body text in the document,
835 a trap,
836 set a small distance above the page bottom,
837 is sprung.
838 .
839 The macro called by the trap draws a line across the page and emits the
840 stored diversion.
841 .
842 Thus,
843 the footnote is rendered.
844 .\" END Keep roughly parallel with first paragraphs of groff.texi node
845 .\" "Deferring Output".
846 .
847 .
848 .\" ====================================================================
849 .SH History
850 .\" ====================================================================
851 .
852 Computer-driven document formatting dates back to the 1960s.
853 .\" John Labovitz points out that Peter Samson's TJ-2 dates to 1963,
854 .\" but since this is a *roff man page, we do not begin our story there.
855 .\" https://johnlabovitz.com/publications/\
856 .\" The-electric-typesetter--The-origins-of-computing-in-typography.pdf
857 .
858 The
859 .I roff
860 system is intimately connected with Unix,
861 but its origins lie with the earlier operating systems CTSS,
862 GECOS,
863 and Multics.
864 .
865 .
866 .\" ====================================================================
867 .SS "The predecessor\[em]\f[I]RUNOFF\f[]"
868 .\" ====================================================================
869 .
870 .IR roff 's
871 ancestor
872 .I RUNOFF
873 was written in the MAD language by Jerry Saltzer
874 to prepare his Ph.D.\& thesis on the Compatible Time Sharing System
875 (CTSS),
876 a project of the Massachusetts Institute of Technology (MIT).
877 .
878 This program is referred to in full capitals,
879 both to distinguish it from its many descendants,
880 and because bits were expensive in those days;
881 five- and six-bit character encodings were still in widespread usage,
882 and mixed-case alphabetics in file names seen as a luxury.
883 .
884 .I RUNOFF
885 introduced a syntax of inlining formatting directives amid document
886 text,
887 by beginning a line with a period
888 (an unlikely occurrence in human-readable material)
889 followed by a \[lq]control word\[rq].
890 .
891 Control words with obvious meaning like \[lq].line length
892 .IR n \[rq]
893 were supported as well as an abbreviation system;
894 the latter came to overwhelm the former in popular usage and later
895 derivatives of the program.
896 .
897 A sample of control words from a
898 .UR http://\:web\:.mit\:.edu/\:Saltzer/\:www/\:publications/\:ctss/\:AH\
899 \:.9\:.01\:.html
900 .I RUNOFF
901 manual of December 1966
902 .UE
903 was documented as follows
904 (with the parameter notation slightly altered).
905 .
906 The abbreviations will be familiar to
907 .I roff
908 veterans.
909 .
910 .
911 .P
912 .ne 10v
913 .TS
914 center;
915 r l
916 rB l.
917 Abbreviation Control word
918 \&.ad .adjust
919 \&.bp .begin page
920 \&.br .break
921 \&.ce .center
922 \&.in .indent \f[I]n\f[]
923 \&.ll .line length \f[I]n\f[]
924 \&.nf .nofill
925 \&.pl .paper length \f[I]n\f[]
926 \&.sp .space [\f[I]n\f[]]
927 .TE
928 .
929 .
930 .P
931 In 1965,
932 MIT's Project MAC teamed with Bell Telephone Laboratories and General
933 Electric (GE) to inaugurate the
934 .UR http://\:www\:.multicians\:.org
935 Multics
936 .UE
937 project.
938 .
939 After a few years,
940 Bell Labs discontinued its participation in Multics,
941 famously prompting the development of Unix.
942 .
943 Meanwhile,
944 Saltzer's
945 .I RUNOFF
946 proved influential,
947 seeing many ports and derivations elsewhere.
948 .
949 .
950 .\" "Morris did one port and called it roff. I did the BCPL one, adding
951 .\" registers, but not macros. Molly Wagner contributed a hyphenation
952 .\" algorithm. Ken and/or Dennis redid roff in PDP-11 assembler. Joe
953 .\" started afresh for the grander nroff, including macros. Then Joe
954 .\" bought a phototypesetter ..."
955 .\" -- https://minnie.tuhs.org/pipermail/tuhs/2018-November/017052.html
956 .P
957 In 1969,
958 Doug McIlroy wrote one such reimplementation,
959 adding extensions,
960 in the BCPL language for a GE 645 running GECOS at the Bell Labs
961 location in Murray Hill,
962 New Jersey.
963 .
964 In its manual,
965 the control commands were termed \[lq]requests\[rq],
966 their two-letter names were canonical,
967 and the control character was configurable with a
968 .B .cc
969 request.
970 .
971 Other familiar requests emerged at this time;
972 no-adjust
973 .RB ( .na ),
974 need
975 .RB ( .ne ),
976 page offset
977 .RB ( .po ),
978 tab configuration
979 .RB ( .ta ,
980 though it worked differently),
981 temporary indent
982 .RB ( .ti ),
983 character translation
984 .RB ( .tr ),
985 and automatic underlining
986 .RB ( .ul ;
987 on
988 .I RUNOFF
989 you had to backspace and underscore in the input yourself).
990 .B .fi
991 to enable filling of output lines got the name it retains to this day.
992 .
993 McIlroy's program also featured a heuristic system for automatically
994 placing hyphenation points,
995 designed and implemented by Molly Wagner.
996 .
997 It furthermore introduced numeric variables,
998 termed registers.
999 .
1000 By 1971,
1001 this program had been ported to Multics and was known as
1002 .IR roff ,
1003 a name McIlroy attributes to Bob Morris,
1004 to distinguish it from CTSS
1005 .IR RUNOFF .
1006 .
1007 .\" GBR can't find a source for this claim (of Bernd's).
1008 .\"Multics
1009 .\".I runoff
1010 .\"added features such as the ability to do two-pass formatting;
1011 .\"it became the main system for Multics documentation and text
1012 .\"processing.
1013 .
1014 .
1015 .\" ====================================================================
1016 .SS "Unix and \f[I]roff\f[]"
1017 .\" ====================================================================
1018 .
1019 McIlroy's
1020 .I roff
1021 was one of the first Unix programs.
1022 .
1023 In Ritchie's term,
1024 it was \[lq]transliterated\[rq] from BCPL to DEC PDP-7 assembly language
1025 .\" see "The Evolution of the Unix Time-Sharing System", Ritchie, 1984
1026 for the fledgling Unix operating system.
1027 .
1028 Automatic hyphenation was managed with
1029 .B .hc
1030 and
1031 .B .hy
1032 requests,
1033 line spacing control was generalized with the
1034 .B .ls
1035 request,
1036 and what later
1037 .IR roff s
1038 would call diversions were available via \[lq]footnote\[rq] requests.
1039 .\" The foregoing features may have been in McIlroy's Multics roff, but
1040 .\" he no longer has documentation for that--only the GECOS version.
1041 .\" GBR's guess is that they were, if we take Ritchie's choice of the
1042 .\" term "transliterated" seriously. GBR further speculates that there
1043 .\" is no reason to suppose that McIlroy's roff was stagnant from
1044 .\" 1969-1971, whereas we have no record of any significant
1045 .\" post-transliteration development of Unix roff. Its request list did
1046 .\" not appear until the 3rd edition manual, and did not change
1047 .\" thereafter. In 7th edition, roff was characterized as "utterly
1048 .\" frozen".
1049 .
1050 This
1051 .I roff
1052 indirectly funded operating systems research at Murray Hill;
1053 AT&T prepared patent applications to the U.S.\& government with it.
1054 .
1055 This arrangement enabled the group to acquire a PDP-11;
1056 .I roff
1057 promptly proved equal to the task of formatting the manual for what
1058 would become known as \[lq]First Edition Unix\[rq],
1059 dated November 1971.
1060 .
1061 .
1062 .P
1063 Output from all of the foregoing programs was limited to line printers
1064 and paper terminals such as the IBM 2471
1065 (based on the Selectric line of typewriters)
1066 and the Teletype Corporation Model 37.
1067 .
1068 Proportionally spaced type was unavailable.
1069 .
1070 .
1071 .\" ====================================================================
1072 .SS "New \f[I]roff\f[] and Typesetter \f[I]roff\f[]"
1073 .\" ====================================================================
1074 .
1075 The first years of Unix were spent in rapid evolution.
1076 .
1077 The practicalities of preparing standardized documents like patent
1078 applications
1079 (and Unix manual pages),
1080 combined with McIlroy's enthusiasm for macro languages,
1081 perhaps created an irresistible pressure to make
1082 .I roff
1083 extensible.
1084 .
1085 Joe Ossanna's
1086 .IR nroff ,
1087 literally a \[lq]new roff\[rq],
1088 was the outlet for this pressure.
1089 .
1090 .\" nroff is listed in the table of contents of the Version 2 manual,
1091 .\" but no man page is present.
1092 By the time of Unix Version\~3
1093 (February 1973)\[em]and still in PDP-11 assembly language\[em]it sported
1094 a swath of features now considered essential to
1095 .I roff
1096 systems:
1097 .
1098 definition of macros
1099 .RB ( .de ),
1100 diversion of text thither
1101 .RB ( .di ),
1102 and removal thereof
1103 .RB ( .rm );
1104 .
1105 trap planting
1106 .RB ( .wh ;
1107 \[lq]when\[rq])
1108 and relocation
1109 .RB ( .ch ;
1110 \[lq]change\[rq]);
1111 .
1112 conditional processing
1113 .RB ( .if );
1114 .
1115 and environments
1116 .RB ( .ev ).
1117 .
1118 Incremental improvements included
1119 .
1120 assignment of the next page number
1121 .RB ( .pn );
1122 .
1123 no-space mode
1124 .RB ( .ns )
1125 and restoration of vertical spacing
1126 .RB ( .rs );
1127 .
1128 the saving
1129 .RB ( .sv )
1130 and output
1131 .RB ( .os )
1132 of vertical space;
1133 .
1134 specification of replacement characters for tabs
1135 .RB ( .tc )
1136 and leaders
1137 .RB ( .lc );
1138 .
1139 configuration of the no-break control character
1140 .RB ( .c2 );
1141 .
1142 shorthand to disable automatic hyphenation
1143 .RB ( .nh );
1144 .
1145 a condensation of what were formerly six different requests for
1146 configuration of page \[lq]titles\[rq]
1147 (headers and footers)
1148 into one
1149 .RB ( .tl )
1150 with a length controlled separately from the line length
1151 .RB ( .lt );
1152 .
1153 automatic line numbering
1154 .RB ( .nm );
1155 .
1156 interactive input
1157 .RB ( .rd ),
1158 which necessitated buffer-flushing
1159 .RB ( .fl ),
1160 and was made convenient with early program cessation
1161 .RB ( .ex );
1162 .
1163 source file inclusion in its modern form
1164 .RB ( .so ;
1165 though
1166 .I RUNOFF
1167 had an \[lq].append\[rq] control word for a similar purpose)
1168 and early advance to the next file argument
1169 .RB ( .nx );
1170 .
1171 ignorable content
1172 .RB ( .ig );
1173 .
1174 and programmable abort
1175 .RB ( .ab ).
1176 .
1177 .
1178 .P
1179 Third Edition Unix also brought the
1180 .MR pipe 2
1181 system call,
1182 the explosive growth of a componentized system based around it,
1183 and a \[lq]filter model\[rq] that remains perceptible today.
1184 .
1185 Equally importantly,
1186 the Bell Labs site in Murray Hill acquired a Graphic Systems C/A/T
1187 phototypesetter,
1188 and with it came the necessity of expanding the capabilities of a
1189 .I roff
1190 system to cope with a variety of proportionally spaced typefaces at
1191 multiple sizes.
1192 .
1193 Ossanna wrote a parallel implementation of
1194 .I nroff
1195 for the C/A/T,
1196 dubbing it
1197 .I troff
1198 (for \[lq]typesetter roff\[rq]).
1199 .
1200 Unfortunately,
1201 surviving documentation does not illustrate what requests were
1202 implemented at this time for C/A/T support;
1203 the
1204 .MR troff 1 \" AT&T
1205 man page in Fourth Edition Unix
1206 (November 1973)
1207 does not feature a request list, \" nor does Unix V6 troff(1) (1975)
1208 unlike
1209 .MR nroff 1 . \" AT&T
1210 .
1211 Apart from typesetter-driven features,
1212 Unix Version\~4
1213 .IR roff s
1214 added string definitions
1215 .RB ( .ds );
1216 made the escape character configurable
1217 .RB ( .ec );
1218 and enabled the user to write diagnostics to the standard error stream
1219 .RB ( .tm ).
1220 .
1221 Around 1974,
1222 empowered with multiple type sizes,
1223 italics,
1224 and a symbol font specially commissioned by Bell Labs from
1225 Graphic Systems,
1226 Kernighan and Lorinda Cherry implemented
1227 .I eqn \" AT&T
1228 for typesetting mathematics.
1229 .
1230 .
1231 In the same year,
1232 for Fifth Edition Unix,
1233 Ossanna combined and reimplemented the two
1234 .IR roff s
1235 in C,
1236 using that language's preprocessor to generate both from a single source
1237 tree.
1238 .
1239 .
1240 .P
1241 Ossanna documented the syntax of the input language to the
1242 .I nroff
1243 and
1244 .I troff
1245 programs in the \[lq]Troff User's Manual\[rq],
1246 first published in 1976,
1247 with further revisions as late as 1992 by Kernighan.
1248 .
1249 (The original version was entitled
1250 \[lq]Nroff/Troff User's Manual\[rq],
1251 which may partially explain why
1252 .I roff
1253 practitioners have tended to refer to it by its AT&T document
1254 identifier,
1255 \[lq]CSTR #54\[rq].)
1256 .
1257 Its final revision serves as the
1258 .I de facto
1259 specification of AT&T
1260 .IR troff , \" AT&T
1261 and all subsequent implementors of
1262 .I roff
1263 systems have done so in its shadow.
1264 .
1265 .
1266 .P
1267 A small and simple set of
1268 .I roff
1269 macros was first used for the manual pages of Unix Version\~4 and
1270 persisted for two further releases,
1271 but the first macro package to be formally described and installed was
1272 .I ms
1273 by Michael Lesk in Version\~6.
1274 .
1275 He also wrote a manual,
1276 \[lq]Typing Documents on the Unix System\[rq],
1277 describing
1278 .I ms
1279 and basic
1280 .IR nroff / troff
1281 usage,
1282 updating it as the package accrued features.
1283 .
1284 Sixth Edition additionally saw the debut of the
1285 .I tbl \" AT&T
1286 preprocessor for formatting tables,
1287 also by Lesk.
1288 .
1289 .
1290 .P
1291 For Unix Version\~7
1292 (January 1979),
1293 McIlroy designed,
1294 implemented,
1295 and documented the
1296 .I man
1297 macro package,
1298 introducing most of the macros described in
1299 .MR groff_man 7
1300 today,
1301 and edited volume 1 of the Version 7 manual using it.
1302 .
1303 Documents composed using
1304 .I ms
1305 featured in volume 2,
1306 edited by Kernighan.
1307 .
1308 .
1309 .\" Thanks to Clem Cole for the following account.
1310 .\" https://minnie.tuhs.org/pipermail/tuhs/2022-January/025143.html
1311 .P
1312 Meanwhile,
1313 .I troff
1314 proved popular even at Unix sites that lacked a C/A/T device.
1315 .
1316 Tom Ferrin of the University of California at San Francisco combined it
1317 with Allen Hershey's popular vector fonts to produce
1318 .IR vtroff ,
1319 which translated
1320 .IR troff 's
1321 output to the command language used by Versatec and Benson-Varian
1322 plotters.
1323 .
1324 .
1325 .P
1326 Ossanna had passed away unexpectedly in 1977,
1327 and after the release of Version 7,
1328 with the C/A/T typesetter becoming supplanted by alternative devices
1329 such as the Mergenthaler Linotron 202,
1330 Kernighan undertook a revision and rewrite of
1331 .I troff
1332 to generalize its design.
1333 .
1334 To implement this revised architecture,
1335 he developed the font and device description file formats and the
1336 page description language that remain in use today.
1337 .
1338 He described these novelties in the article
1339 \[lq]A Typesetter-independent TROFF\[rq],
1340 last revised in 1982,
1341 and like the
1342 .I troff
1343 manual itself,
1344 it is widely known by a shorthand,
1345 \[lq]CSTR #97\[rq].
1346 .\" Further entertaining reading can be found at:
1347 .\" <https://www.cs.princeton.edu/~bwk/202/summer.reconstructed.pdf>.
1348 .
1349 .
1350 .P
1351 Kernighan's innovations prepared
1352 .I troff
1353 well for the introduction of the Adobe PostScript language in 1982 and a
1354 vibrant market in laser printers with built-in interpreters for it.
1355 .
1356 An output driver for PostScript,
1357 .IR dpost ,
1358 was swiftly developed.
1359 .
1360 However,
1361 AT&T's software licensing practices kept
1362 Ossanna's
1363 .IR troff ,
1364 with its tight coupling to the C/A/T's capabilities,
1365 in parallel distribution with device-independent
1366 .I troff
1367 throughout the 1980s.
1368 .
1369 Today,
1370 however,
1371 all actively maintained
1372 .IR troff s
1373 follow Kernighan's device-independent design.
1374 .
1375 .
1376 .\" ====================================================================
1377 .SS "\f[I]groff\f[]\[em]a free \f[I]roff\f[] from GNU"
1378 .\" ====================================================================
1379 .
1380 The most important free
1381 .I roff
1382 project historically has been
1383 .IR groff ,
1384 the GNU implementation of
1385 .IR troff ,
1386 developed by James Clark starting in 1989 and distributed under
1387 .UR http://\:www\:.gnu\:.org/\:copyleft
1388 copyleft
1389 .UE
1390 licenses,
1391 ensuring to all the availability of source code and the freedom to
1392 modify and redistribute it,
1393 properties unprecedented in
1394 .I roff
1395 systems to that point.
1396 .
1397 .I groff
1398 rapidly attracted contributors,
1399 and has served as a replacement for almost all applications of AT&T
1400 .I troff
1401 (exceptions include
1402 .IR mv ,
1403 a macro package for preparation of viewgraphs and slides,
1404 and the
1405 .I ideal
1406 preprocessor,
1407 which produces diagrams from mathematical constraints).
1408 .
1409 Beyond that,
1410 it has added numerous features;
1411 see
1412 .MR groff_diff 7 .
1413 .
1414 Since its inception and for at least the following three decades,
1415 it has been used by practically all GNU/Linux and BSD operating systems.
1416 .
1417 .
1418 .P
1419 .I groff
1420 continues to be developed,
1421 is available for almost all operating systems in common use
1422 (along with several obscure ones),
1423 and is free.
1424 .
1425 These factors make
1426 .I groff
1427 the
1428 .I de facto
1429 .I roff
1430 standard today.
1431 .
1432 .
1433 .\" ====================================================================
1434 .SS "Other free \f[I]roff\f[]s"
1435 .\" ====================================================================
1436 .
1437 In 2007, \" TODO: verify
1438 Caldera/SCO and Sun Microsystems,
1439 having acquired rights to AT&T Documenter's Workbench (DWB)
1440 .I troff
1441 (a descendant of the Bell Labs code),
1442 released it under a free but GPL-incompatible license.
1443 .
1444 .UR https://\:github\:.com/\:n\-t\-roff/\:DWB3.3
1445 This implementation
1446 .UE
1447 was made portable to modern POSIX systems,
1448 and adopted and enhanced first by Gunnar Ritter and then Carsten Kunze
1449 to produce
1450 .UR https://github.com/n-t-roff/heirloom-doctools
1451 Heirloom Doctools
1452 .I troff
1453 .UE .
1454 .
1455 .
1456 .P
1457 .\" https://lists.gnu.org/archive/html/groff/2013-07/msg00001.html
1458 In July 2013,
1459 Ali Gholami Rudi announced
1460 .UR https://\:github\:.com/\:aligrudi/\:neatroff
1461 .I neatroff
1462 .UE ,
1463 a permissively licensed new implementation.
1464 .
1465 .
1466 .P
1467 Another descendant of DWB
1468 .I troff \" DWB
1469 is part of
1470 .UR https://\:9fans\:.github\:.io/\:plan9port/
1471 Plan\~9 from User Space
1472 .UE .
1473 .
1474 Since 2021,
1475 this
1476 .I troff \" Plan 9 from User Space
1477 has been available under permissive terms.
1478 .
1479 .
1480 .\" ====================================================================
1481 .SH "Using \f[I]roff\f[]"
1482 .\" ====================================================================
1483 .
1484 When you read a man page,
1485 often a
1486 .I roff
1487 is the program rendering it.
1488 .
1489 Some
1490 .I roff
1491 implementations provide wrapper programs that make it easy to use the
1492 .I roff
1493 system from the shell's command line.
1494 .
1495 These can be specific to a macro package,
1496 like
1497 .MR mmroff 1 ,
1498 or more general.
1499 .
1500 .MR groff 1
1501 provides command-line options sparing the user from constructing the
1502 long,
1503 order-dependent pipelines familiar to AT&T
1504 .I troff
1505 users.
1506 .
1507 Further,
1508 a heuristic program,
1509 .MR grog 1 ,
1510 is available to infer from a document's contents which
1511 .I groff
1512 arguments should be used to process it.
1513 .
1514 .
1515 .\" ====================================================================
1516 .SS "The \f[I]roff\f[] pipeline"
1517 .\" ====================================================================
1518 .
1519 A typical
1520 .I roff
1521 document is prepared by running one or more processors in series,
1522 followed by a a formatter program and then an output driver
1523 (or \[lq]device postprocessor\[rq]).
1524 .
1525 Commonly,
1526 these programs are structured into a pipeline;
1527 that is,
1528 each is run in sequence such that the output of one is
1529 taken as the input
1530 to the next,
1531 without passing through secondary storage.
1532 .
1533 (On non-Unix systems,
1534 pipelines may have to be simulated with temporary files.)
1535 .
1536 .
1537 .RS
1538 .PP
1539 .EX
1540 .RI $\~ preproc1 \~\c
1541 .BI <\~ input-file \~|\~ preproc2 \~|\~\c
1542 .RB .\|.\|.\&\~ "| troff\~"\c
1543 .RI [ option ]\~\c
1544 .RB .\|.\|.\&\~ \[rs]
1545 .BI " |\~" output-driver \" 4 leading spaces
1546 .EE
1547 .RE
1548 .
1549 .
1550 .P
1551 Once all preprocessors have run,
1552 they deliver pure
1553 .I roff
1554 language input to the formatter,
1555 which in turn generates a document in a page description language that
1556 is then interpreted by a postprocessor for viewing,
1557 printing,
1558 or further processing.
1559 .
1560 .
1561 .P
1562 Each program interprets input in a language that is independent of the
1563 others;
1564 some are purely descriptive,
1565 as with
1566 .MR \%tbl 1
1567 and
1568 .I roff
1569 output,
1570 and some permit the definition of macros,
1571 as with
1572 .MR \%eqn 1
1573 and
1574 .I roff
1575 input.
1576 .
1577 .
1578 Most
1579 .I roff
1580 input files employ the macros of a document formatting package,
1581 intermixed with instructions for one or more preprocessors,
1582 and seasoned with escape sequences and requests from the
1583 .I roff
1584 language.
1585 .
1586 Some documents are simpler still,
1587 since their formatting packages discourage direct use of
1588 .I roff
1589 requests;
1590 man pages are a prominent example.
1591 .
1592 Many features of the
1593 .I roff
1594 language are seldom needed by users;
1595 only authors of macro packages require a substantial command of them.
1596 .
1597 .
1598 .\" ====================================================================
1599 .SS Preprocessors
1600 .\" ====================================================================
1601 .
1602 A
1603 .I roff
1604 preprocessor is a program that,
1605 directly or ultimately,
1606 generates output in the
1607 .I roff
1608 language.
1609 .
1610 Typically, \" preconv is an exception.
1611 each preprocessor defines a language of its own that transforms its
1612 input into that for
1613 .I roff
1614 or another preprocessor.
1615 .
1616 As an example of the latter,
1617 .I chem \" generic
1618 produces
1619 .I pic \" generic
1620 input.
1621 .
1622 Preprocessors must consequently be run in an appropriate order;
1623 .MR groff 1
1624 handles this automatically for all preprocessors supplied by the GNU
1625 .I roff
1626 system.
1627 .
1628 .
1629 .P
1630 Portions of the document written in preprocessor languages are usually
1631 .\" preconv is the exception again.
1632 bracketed by tokens that look like
1633 .I roff
1634 macro calls.
1635 .
1636 .I roff
1637 preprocessor programs transform only the regions of the document
1638 intended for them.
1639 .\" In preconv's case, that's the whole document.
1640 .
1641 When a preprocessor language is used by a document,
1642 its corresponding program must process it before the input is seen by
1643 the formatter,
1644 or incorrect rendering is almost guaranteed.
1645 .
1646 .
1647 .P
1648 GNU
1649 .I roff
1650 provides several preprocessors,
1651 including
1652 .IR \%eqn ,
1653 .IR \%grn ,
1654 .IR \%pic ,
1655 .IR \%tbl ,
1656 .IR \%refer ,
1657 and
1658 .IR \%soelim .
1659 .
1660 See
1661 .MR groff 1
1662 for a complete list.
1663 .
1664 Other preprocessors for
1665 .I roff
1666 systems are known.
1667 .
1668 .
1669 .P
1670 .RS
1671 .TS
1672 tab (@);
1673 Li L.
1674 dformat@depicts data structures;
1675 grap@constructs statistical charts; and
1676 ideal@draws diagrams using a constraint-based language.
1677 .TE
1678 .RE
1679 .
1680 .
1681 .\" ====================================================================
1682 .SS "Formatter programs"
1683 .\" ====================================================================
1684 .
1685 A
1686 .I roff
1687 formatter transforms
1688 .I roff
1689 language input into a single file in a page description language,
1690 described in
1691 .MR groff_out 5 ,
1692 intended for processing by a selected device.
1693 .
1694 This page description language is specialized in its parameters,
1695 but not its syntax,
1696 for the selected device;
1697 the format is
1698 .RI device- independent ,
1699 but not
1700 .RI device- agnostic .
1701 .
1702 The parameters the formatter uses to arrange the document are stored in
1703 .I device
1704 and
1705 .IR "font description files" ;
1706 see
1707 .MR groff_font 5 .
1708 .
1709 .
1710 .P
1711 AT&T Unix
1712 had two formatters\[em]\c
1713 .I nroff
1714 for terminals,
1715 and
1716 .I troff
1717 for typesetters.
1718 .
1719 Often,
1720 the name
1721 .I troff
1722 is used loosely to refer to both.
1723 .
1724 When generalizing thus,
1725 .I groff
1726 documentation prefers the term
1727 .RI \[lq] roff \[rq].
1728 .
1729 In GNU
1730 .IR roff ,
1731 the formatter program is always
1732 .MR \%troff 1 .
1733 .
1734 .
1735 .\" ====================================================================
1736 .SS "Devices and output drivers"
1737 .\" ====================================================================
1738 .
1739 To a
1740 .I roff
1741 system,
1742 a
1743 .I device
1744 is a hardware interface like a printer,
1745 a text or graphical terminal,
1746 or a standardized file format that unrelated software can interpret.
1747 .
1748 An
1749 .I output driver
1750 is a program that parses the output of
1751 .I troff \" generic
1752 and produces instructions specific to the device or file format it
1753 supports.
1754 .
1755 An output driver might support multiple devices,
1756 particularly if they are similar.
1757 .
1758 .
1759 .P
1760 The names of the devices and their driver programs are not standardized.
1761 .
1762 Technological fashions evolve;
1763 the devices used for document preparation when AT&T
1764 .I troff \" AT&T
1765 was first written in the 1970s are no longer used in production
1766 environments.
1767 .
1768 Device capabilities have tended to increase,
1769 improving resolution and font repertoire,
1770 and adding color output and hyperlinking.
1771 .
1772 Further,
1773 to reduce file size and processing time,
1774 AT&T
1775 .IR troff 's \" AT&T
1776 page description language placed low limits on the magnitudes of some
1777 quantities it could represent.
1778 .
1779 Its PostScript output driver,
1780 .MR dpost 1 ,
1781 had a resolution of 720 units per inch;
1782 .IR groff 's
1783 .MR grops 1
1784 uses 72,000.
1785 .
1786 .
1787 .\".P
1788 .\"Today the operating systems provide device drivers for most
1789 .\"printer-like hardware, so it isn't necessary to write a special
1790 .\"hardware postprocessor for each printer.
1791 .\" XXX? No they don't. Instead printers interpret PS or PDF directly.
1792 .\" With a TCP/IP protocol stack and an HTTP server to accept POSTed
1793 .\" documents for printing.
1794 .
1795 .
1796 .\" ====================================================================
1797 .SH "\f[I]roff\f[] programming"
1798 .\" ====================================================================
1799 .
1800 Documents using
1801 .I roff
1802 are normal text files interleaved with
1803 .I roff
1804 formatting elements.
1805 .
1806 The
1807 .I roff
1808 language is powerful enough to support arbitrary computation and
1809 it supplies facilities that encourage extension.
1810 .
1811 The primary such facility is macro definition;
1812 with this feature,
1813 macro packages have been developed that are tailored for particular
1814 applications.
1815 .
1816 .
1817 .\" ====================================================================
1818 .SS "Macro packages"
1819 .\" ====================================================================
1820 .
1821 Macro packages can have a much smaller vocabulary than
1822 .I roff
1823 itself;
1824 this trait combined with their domain-specific nature can make them easy
1825 to acquire and master.
1826 .
1827 The macro definitions of a package are typically kept in a file called
1828 .IB name .tmac
1829 (historically,
1830 .BI tmac. name\/\c\" Italic correction comes before \c !
1831 ).
1832 .
1833 Find details on the naming and placement of macro packages in
1834 .MR groff_tmac 5 .
1835 .
1836 .
1837 .P
1838 A macro package anticipated for use in a document can be declared to
1839 the formatter by the command-line option
1840 .BR \-m ;
1841 see
1842 .MR \%troff 1 .
1843 .
1844 It can alternatively be specified within a document using the
1845 .B mso
1846 request of the
1847 .I groff
1848 language;
1849 see
1850 .MR groff 7 .
1851 .
1852 .
1853 .P
1854 Well-known macro packages include
1855 .I man
1856 for traditional man pages and
1857 .I mdoc
1858 for BSD-style manual pages.
1859 .
1860 Macro packages for typesetting books,
1861 articles,
1862 and letters include
1863 .I ms
1864 (from \[lq]manuscript macros\[rq]),
1865 .I me
1866 (named by a system administrator from the first name of its creator,
1867 Eric Allman),
1868 .I mm
1869 (from \[lq]memorandum macros\[rq]),
1870 and
1871 .IR mom ,
1872 a punningly named package exercising many
1873 .I groff
1874 extensions.
1875 .
1876 See
1877 .MR groff_tmac 5
1878 for more.
1879 .
1880 .
1881 .\" ====================================================================
1882 .SS "The \f[I]roff\f[] formatting language"
1883 .\" ====================================================================
1884 .
1885 .\" TODO: Integrate this subsection with subsection "Other language
1886 .\" elements".
1887 The
1888 .I roff
1889 language provides requests,
1890 escape sequences,
1891 macro definition facilities,
1892 string variables,
1893 registers for storage of numbers or dimensions,
1894 and control of execution flow.
1895 .
1896 The theoretically minded will observe that a
1897 .I roff
1898 is not a mere markup language,
1899 but Turing-complete.
1900 .
1901 It has storage
1902 (registers),
1903 it can perform tests
1904 (as in conditional expressions like
1905 .RB \[lq] "(\[rs]n[i] >= 1)" \[rq]),
1906 its
1907 .\" Kerning between bold "i" and "f" and roman \[lq], \[rq] is tight.
1908 .RB \[lq] \|if\| \[rq]
1909 and related requests alter the flow of control,
1910 and macro definition permits unbounded recursion.
1911 .
1912 .
1913 .P
1914 .I Requests
1915 and
1916 .I escape sequences
1917 are instructions,
1918 predefined parts of the language,
1919 that perform formatting operations,
1920 interpolate stored material,
1921 or otherwise change the state of the parser.
1922 .
1923 The user can define their own request-like elements by composing
1924 together text,
1925 requests,
1926 and escape sequences
1927 .I "ad libitum."
1928 .
1929 .
1930 A document writer will not (usually) note any difference in usage for
1931 requests or macros;
1932 both are found on control lines.
1933 .
1934 However,
1935 there is a distinction;
1936 requests take either a fixed number of arguments
1937 (sometimes zero),
1938 silently ignoring any excess,
1939 or consume the rest of the input line,
1940 whereas macros can take a variable number of arguments.
1941 .
1942 Since arguments are separated by spaces,
1943 macros require a means of embedding a space in an argument;
1944 in other words,
1945 of quoting it.
1946 .
1947 This then demands a mechanism of embedding the quoting character itself,
1948 in case
1949 .I it
1950 is needed literally in a macro argument.
1951 .
1952 AT&T
1953 .I troff
1954 had complex rules involving the placement and repetition of the double
1955 quote to achieve both aims.
1956 .
1957 .I groff
1958 cuts this knot by supporting a special character escape sequence for the
1959 neutral double quote,
1960 .\" The kerning between a roman \[lq] and a bold backslash is tight.
1961 .RB \[lq] \|\[rs][dq] \[rq],
1962 which never performs quoting in the typesetting language,
1963 but is simply a glyph,
1964 .RB \[oq] \[dq] \[cq].
1965 .
1966 .
1967 .P
1968 .I Escape sequences
1969 start with a backslash,
1970 .RB \[lq] \|\[rs] \[rq].
1971 .
1972 They can appear almost anywhere,
1973 even in the midst of text on a line,
1974 and implement various features,
1975 including the insertion of special characters with
1976 .RB \[lq] \|\[rs](\f[BI]xx\f[] \[rq]
1977 or
1978 .RB \[lq] \|\[rs][\f[BI]xxx\f[]] \[rq],
1979 break suppression at input line endings with
1980 .RB \[lq] \|\[rs]c \[rq],
1981 font changes with
1982 .RB \[lq] \|\[rs]f\| \[rq],
1983 type size changes with
1984 .RB \[lq] \|\[rs]s \[rq],
1985 in-line comments with
1986 .RB \[lq] \|\[rs]\[dq] \[rq],
1987 and many others.
1988 .
1989 .
1990 .P
1991 .I Strings
1992 store text.
1993 .
1994 They are populated with the
1995 .B ds
1996 request and interpolated using the
1997 .B \[rs]*
1998 escape sequence.
1999 .
2000 .
2001 .P
2002 .I Registers
2003 store numbers and measurements.
2004 .
2005 A register can be set with the request
2006 .B nr
2007 and its value can be retrieved by the escape sequence
2008 .BR "\[rs]n" .
2009 .
2010 .
2011 .\" ====================================================================
2012 .SH "File naming conventions"
2013 .\" ====================================================================
2014 .
2015 The structure or content of a file name,
2016 beyond its location in the file system,
2017 is not significant to
2018 .I roff
2019 tools.
2020 .
2021 .I roff
2022 documents employing \[lq]full-service\[rq] macro packages
2023 (see
2024 .MR groff_tmac 5 )
2025 tend to be named with a suffix identifying the package;
2026 we thus see file names ending in
2027 .IR .man ,
2028 .IR .ms ,
2029 .IR .me ,
2030 .IR .mm ,
2031 and
2032 .IR .mom ,
2033 for instance.
2034 .
2035 When installed,
2036 man pages tend to be named with the manual's section number as the
2037 suffix.
2038 .
2039 For example,
2040 the file name for this document is
2041 .IR roff.7 .
2042 .
2043 Practice for
2044 \[lq]raw\[rq]
2045 .I roff
2046 documents is less consistent;
2047 they
2048 are sometimes seen with a
2049 .I .t
2050 suffix.
2051 .
2052 .
2053 .\" BEGIN Keep parallel with groff.texi node "Input Conventions".
2054 .\" ====================================================================
2055 .SH "Input conventions"
2056 .\" ====================================================================
2057 .
2058 Since
2059 .I \%troff
2060 fills text automatically,
2061 it is common practice in the
2062 .I roff
2063 language to avoid visual composition of text in input files:
2064 the esthetic appeal of the formatted output is what matters.
2065 .
2066 Therefore,
2067 .I roff
2068 input should be arranged such that it is easy for authors and
2069 maintainers to compose and develop the document,
2070 understand the syntax of
2071 .I roff
2072 requests,
2073 macro calls,
2074 and preprocessor languages used,
2075 and predict the behavior of the
2076 formatter.
2077 .
2078 Several traditions have accrued in service of these goals.
2079 .
2080 .
2081 .IP \[bu] 2n
2082 Follow sentence endings in the input with newlines to ease their
2083 recognition.
2084 .\" Texinfo: (@pxref{Sentences}).
2085 It is frequently convenient to end text lines after colons and
2086 semicolons as well,
2087 as these typically precede independent clauses.
2088 .
2089 Consider doing so after commas;
2090 they often occur in lists that become easy to scan when itemized by
2091 line,
2092 or constitute supplements to the sentence that are added,
2093 deleted,
2094 or updated to clarify it.
2095 .
2096 Parenthetical and quoted phrases are also good candidates for placement
2097 on text lines by themselves.
2098 .
2099 .
2100 .IP \[bu]
2101 Set your text editor's line length to 72 characters or fewer;
2102 see the subsections below.
2103 .\" Texinfo:
2104 .\" @footnote{Emacs: @code{fill-column: 72}; Vim: @code{textwidth=72}}
2105 .
2106 This limit,
2107 combined with the previous item of advice,
2108 makes it less common that an input line will wrap in your text editor,
2109 and thus will help you perceive excessively long constructions in your
2110 text.
2111 .
2112 Recall that natural languages originate in speech,
2113 not writing,
2114 and that punctuation is correlated with pauses for breathing and changes
2115 in prosody.
2116 .
2117 .
2118 .IP \[bu]
2119 Use
2120 .B \[rs]&
2121 after
2122 .RB \[lq] !\& \[rq],
2123 .RB \[lq] ?\& \[rq],
2124 and
2125 .RB \[lq] .\& \[rq]
2126 if they are followed by space,
2127 tab,
2128 or newline characters and don't end a sentence.
2129 .
2130 .
2131 .IP \[bu]
2132 In filled text lines,
2133 use
2134 .B \[rs]&
2135 before
2136 .RB \[lq] .\& \[rq]
2137 and
2138 .RB \[lq] \[aq] \[rq]
2139 if they are preceded by space,
2140 so that reflowing the input doesn't turn them into control lines.
2141 .
2142 .
2143 .IP \[bu]
2144 Do not use spaces to perform indentation or align columns of a table.
2145 Leading spaces are reliable when text is not being filled.
2146 .
2147 .
2148 .IP \[bu]
2149 Comment your document.
2150 .
2151 It is never too soon to apply comments to record information of use to
2152 future document maintainers
2153 (including your future self).
2154 .\" Texinfo: We thus introduce another escape sequence, @code{\"}, which
2155 The
2156 .B \[rs]\[dq]
2157 escape sequence
2158 causes
2159 .I \%troff
2160 to ignore the remainder of the input line.
2161 .
2162 .
2163 .IP \[bu]
2164 Use the empty request\[em]a control character followed immediately by a
2165 newline\[em]to visually manage separation of material in input files.
2166 .
2167 Many of the
2168 .I groff
2169 project's own documents use an empty request between sentences,
2170 after macro definitions,
2171 and where a break is expected,
2172 and two empty requests between paragraphs or other requests or macro
2173 calls that will introduce vertical space into the document.
2174 .
2175 You can combine the empty request with the comment escape sequence to
2176 include whole-line comments in your document,
2177 and even \[lq]comment out\[rq] sections of it.
2178 .
2179 .
2180 .P
2181 .\" Texinfo: We conclude this section with an example
2182 An example sufficiently long to illustrate most of the above suggestions
2183 in practice follows.
2184 .
2185 .\" Texinfo: For the purpose of fitting the example between the margins
2186 .\" of this manual with the font used for its typeset version,
2187 .\" we have shortened the input line length to 56
2188 .\" columns.
2189 .\" Texinfo: As before,
2190 .
2191 An arrow \[->] indicates a tab character.
2192 .
2193 .
2194 .P
2195 .RS
2196 .EX
2197 \&.\[rs]" nroff this_file.roff | less
2198 \&.\[rs]" groff \-T ps this_file.roff > this_file.ps
2199 \[->]The theory of relativity is intimately connected with
2200 the theory of space and time.
2201 \&.
2202 I shall therefore begin with a brief investigation of
2203 the origin of our ideas of space and time,
2204 although in doing so I know that I introduce a
2205 controversial subject.\& \[rs]" remainder of paragraph elided
2206 \&.
2207 .ne 3v \" Don't let a page break hide the blank line from the reader.
2208 \&.
2209 \&
2210 \[->]The experiences of an individual appear to us arranged
2211 in a series of events;
2212 in this series the single events which we remember
2213 appear to be ordered according to the criterion of
2214 \[rs][lq]earlier\[rs][rq] and \[rs][lq]later\[rs][rq], \[rs]" punct \
2215 swapped
2216 which cannot be analysed further.
2217 \&.
2218 There exists,
2219 therefore,
2220 for the individual,
2221 an I\-time,
2222 or subjective time.
2223 \&.
2224 This itself is not measurable.
2225 \&.
2226 I can,
2227 indeed,
2228 associate numbers with the events,
2229 in such a way that the greater number is associated with
2230 the later event than with an earlier one;
2231 but the nature of this association may be quite
2232 arbitrary.
2233 \&.
2234 This association I can define by means of a clock by
2235 comparing the order of events furnished by the clock
2236 with the order of a given series of events.
2237 \&.
2238 We understand by a clock something which provides a
2239 series of events which can be counted,
2240 and which has other properties of which we shall speak
2241 later.
2242 \&.\[rs]" Albert Einstein, _The Meaning of Relativity_, 1922
2243 .EE
2244 .RE
2245 .\" END Keep parallel with groff.texi node "Input Conventions".
2246 .
2247 .
2248 .\" ====================================================================
2249 .SS "Editing with Emacs"
2250 .\" ====================================================================
2251 .
2252 Official GNU doctrine holds that the best program for editing a
2253 .I roff
2254 document is Emacs; see
2255 .MR emacs 1 .
2256 .
2257 It provides an
2258 .I nroff
2259 major mode that is suitable for all kinds of
2260 .I roff
2261 dialects.
2262 .
2263 This mode can be activated by the following methods.
2264 .
2265 .
2266 .P
2267 When editing a file within Emacs the mode can be changed by typing
2268 .RI \[lq] M-x
2269 .BR nroff\-mode \[rq],
2270 where
2271 .I M-x
2272 means to hold down the meta key
2273 (often labelled \[lq]Alt\[rq])
2274 while pressing and releasing the \[lq]x\[rq] key.
2275 .\" Why is this sort of thing not in intro(1)?
2276 .
2277 .
2278 .P
2279 It is also possible to have the mode automatically selected when a
2280 .I roff
2281 file is loaded into the editor.
2282 .
2283 .
2284 .IP \(bu 2n
2285 The most general method is to include file-local variables at the end of
2286 the file;
2287 we can also configure the fill column this way.
2288 .
2289 .
2290 .RS
2291 .IP
2292 .EX
2293 \&.\[rs]" Local Variables:
2294 \&.\[rs]" fill\-column: 72
2295 \&.\[rs]" mode: nroff
2296 \&.\[rs]" End:
2297 .EE
2298 .RE
2299 .
2300 .IP \(bu
2301 Certain file name extensions,
2302 such as those commonly used by man pages,
2303 trigger the automatic activation of the
2304 .I nroff
2305 mode.
2306 .
2307 .
2308 .br
2309 .ne 3v
2310 .IP \(bu
2311 Technically,
2312 having the sequence
2313 .
2314 .
2315 .RS
2316 .IP
2317 .EX
2318 \&.\[rs]" \%\-*\- nroff \-*\-
2319 .EE
2320 .RE
2321 .
2322 .
2323 .IP
2324 in the first line of a file will cause Emacs to enter the
2325 .I nroff
2326 major mode when it is loaded into the buffer.
2327 .
2328 Unfortunately,
2329 some implementations of the
2330 .MR man 1
2331 program are confused by this practice,
2332 so we discourage it.
2333 .
2334 .
2335 .\" ====================================================================
2336 .SS "Editing with Vim"
2337 .\" ====================================================================
2338 .
2339 .\" TODO: elvis, vile. Nvi does not support highlighting at all, and
2340 .\" gedit does but has no rules for roff yet. Other editors TBD.
2341 Other editors provide support for
2342 .IR roff -style
2343 files too,
2344 such as
2345 .MR vim 1 ,
2346 an extension of the
2347 .MR vi 1
2348 program.
2349 .
2350 Vim's highlighting can be made to recognize
2351 .I roff
2352 files by setting the
2353 .B filetype
2354 option in a Vim
2355 .IR modeline .
2356 .
2357 For this feature to work,
2358 your copy of
2359 .I vim
2360 must be built with support for,
2361 and configured to enable,
2362 several features;
2363 consult the editor's online help topics
2364 \[lq]auto\-setting\[rq],
2365 \[lq]filetype\[rq],
2366 and \[lq]syntax\[rq].
2367 .
2368 Then put the following at the end of your
2369 .I roff
2370 files,
2371 after any Emacs configuration:
2372 .\" ...because Emacs pattern-matches against 3000 bytes from the end of
2373 .\" the buffer [or until hitting a 0x0C (FF, form-feed control)] for
2374 .\" "Local Variables:", but Vim only checks as many lines as its
2375 .\" 'modelines' variable tells it to. A common default is "5", but
2376 .\" Emacs settings can be longer than that.
2377 .
2378 .
2379 .RS
2380 .IP
2381 .EX
2382 \&.\[rs]" vim: set filetype=groff textwidth=72:
2383 .EE
2384 .RE
2385 .
2386 .
2387 .P
2388 Replace \[lq]groff\[rq] in the above with \[lq]nroff\[rq] if you want
2389 highlighting that does
2390 .I not
2391 recognize many of the GNU extensions to
2392 .IR roff ,
2393 such as request,
2394 register,
2395 and string names longer than two characters.
2396 .
2397 .
2398 .\" ====================================================================
2399 .SH Authors
2400 .\" ====================================================================
2401 .
2402 This document was written by
2403 .MT groff\-bernd\:.warken\-72@\:web\:.de
2404 Bernd Warken
2405 .ME
2406 and
2407 .MT g.branden\:.robinson@\:gmail\:.com
2408 G.\& Branden Robinson
2409 .ME .
2410 .
2411 .
2412 .\" ====================================================================
2413 .SH "See also"
2414 .\" ====================================================================
2415 .
2416 Much
2417 .I roff
2418 documentation is available.
2419 .
2420 The Bell Labs papers describing AT&T
2421 .I troff
2422 remain available,
2423 and
2424 .I groff
2425 is documented comprehensively. \" ...one hopes.
2426 .
2427 .
2428 .\" ====================================================================
2429 .SS "Internet sites"
2430 .\" ====================================================================
2431 .
2432 .P
2433 .UR https://\:github\:.com/\:larrykollar/\:Unix\-Text\-Processing
2434 .I Unix Text Processing
2435 .UE ,
2436 by Dale Dougherty and Tim O'Reilly,
2437 1987,
2438 Hayden Books.
2439 .
2440 This well-regarded text brings the reader from a state of no knowledge
2441 of Unix or text editing
2442 (if necessary)
2443 to sophisticated computer-aided typesetting.
2444 .
2445 It has been placed under a free software license by its authors and
2446 updated by a team of
2447 .I groff
2448 contributors and enthusiasts.
2449 .
2450 .
2451 .P
2452 .UR http://\:manpages\:.bsd\:.lv/\:history\:.html
2453 \[lq]History of Unix Manpages\[rq]
2454 .UE ,
2455 an online article maintained by the mdocml project,
2456 provides an overview of
2457 .I roff
2458 development from Saltzer's
2459 .I RUNOFF
2460 to 2008,
2461 with links to original documentation and recollections of the authors
2462 and their contemporaries.
2463 .
2464 .
2465 .P
2466 .UR http://\:www\:.troff\:.org/
2467 troff.org
2468 .UE ,
2469 Ralph Corderoy's
2470 .I troff
2471 site,
2472 provides an overview and pointers to much historical
2473 .I roff
2474 information.
2475 .
2476 .
2477 .P
2478 .UR http://\:www\:.multicians\:.org/
2479 Multicians
2480 .UE ,
2481 a site by Multics enthusiasts,
2482 contains a lot of information on the MIT projects CTSS and Multics,
2483 including
2484 .IR RUNOFF ;
2485 it is especially useful for its glossary and the many links to
2486 historical documents.
2487 .
2488 .
2489 .P
2490 .UR http://\:www\:.tuhs\:.org/\:Archive/
2491 The Unix Archive
2492 .UE ,
2493 curated by the Unix Heritage Society,
2494 provides the source code and some binaries of historical Unices
2495 (including the source code of some versions of
2496 .I troff
2497 and its documentation)
2498 contributed by their copyright holders.
2499 .
2500 .
2501 .P
2502 .UR http://\:web\:.mit\:.edu/\:Saltzer/\:www/\:publications/\
2503 \:pubs\:.html
2504 Jerry Saltzer's home page
2505 .UE
2506 stores some documents using the original
2507 .I RUNOFF
2508 formatting language.
2509 .
2510 .
2511 .P
2512 .UR http://\:www\:.gnu\:.org/\:software/\:groff
2513 .I groff
2514 .UE ,
2515 GNU
2516 .IR roff 's
2517 web site,
2518 provides convenient access to
2519 .IR groff 's
2520 source code repository,
2521 bug tracker,
2522 and mailing lists
2523 (including archives and the subscription interface).
2524 .
2525 .
2526 .\" ====================================================================
2527 .SS "Historical \f[I]roff\f[] documentation"
2528 .\" ====================================================================
2529 .
2530 Many AT&T
2531 .I troff
2532 documents are available online,
2533 and can be found at Ralph Corderoy's site
2534 (see above)
2535 or via Internet search.
2536 .
2537 .
2538 .P
2539 Of foremost significance are two mentioned in section \[lq]History\[rq]
2540 above,
2541 describing the language and its device-independent implementation,
2542 respectively.
2543 .
2544 .
2545 .P
2546 \[lq]Troff User's Manual\[rq]
2547 by Joseph F.\& Ossanna,
2548 1976
2549 (revised by Brian W.\& Kernighan,
2550 1992),
2551 AT&T Bell Laboratories Computing Science Technical Report No.\& 54.
2552 .
2553 .
2554 .P
2555 \[lq]A Typesetter-independent TROFF\[rq]
2556 by Brian W.\& Kernighan,
2557 1982,
2558 AT&T Bell Laboratories Computing Science Technical Report No.\& 97.
2559 .
2560 .
2561 .P
2562 You can obtain many relevant Bell Labs papers in PDF from
2563 .UR https://\:github\:.com/\:bwarken/\:roff_classical\:.git
2564 Bernd Warken's
2565 \[lq]roff classical\[rq]
2566 GitHub repository
2567 .UE .
2568 .
2569 .
2570 .\" ====================================================================
2571 .SS "Manual pages"
2572 .\" ====================================================================
2573 .
2574 As a system of multiple components,
2575 a
2576 .I roff
2577 system potentially has many man pages,
2578 each describing an aspect of it.
2579 .
2580 Unfortunately,
2581 there is no consistent naming scheme for these pages among the different
2582 .I roff
2583 implementations.
2584 .
2585 .
2586 .P
2587 For GNU
2588 .IR roff ,
2589 the
2590 .MR groff 1
2591 man page enumerates all man pages distributed with the system,
2592 and individual pages frequently refer to external resources as well as
2593 manuals distributed with
2594 .I groff
2595 on a variety of topics.
2596 .
2597 .
2598 .P
2599 With other
2600 .IR roff s,
2601 you are on your own,
2602 but
2603 .MR troff 1 \" foreign troff
2604 might be a good starting point.
2605 .
2606 .
2607 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
2608 .cp \n[*groff_roff_7_man_C]
2609 .do rr *groff_roff_7_man_C
2610 .
2611 .
2612 .\" Local Variables:
2613 .\" fill-column: 72
2614 .\" mode: nroff
2615 .\" End:
2616 .\" vim: set filetype=groff textwidth=72: