Debian Codegraph @

upstream/fedora-44/man7/roff.groff.7

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