Debian Codegraph @

upstream/debian-unstable/man7/roff.7

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