1 '\" t -- preprocess: tbl(1)
5 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
7 Copyright (C) 2000 - 2004, 2006 - 2008
8 Free Software Foundation, Inc.
9 written by Bernd Warken <bwarken@mayn.de>
10 maintained by Werner Lemberg <wl@gnu.org>
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.1 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being this .ig-section and AUTHORS, with no
16 Front-Cover Texts, and with no Back-Cover Texts.
18 You should have received a copy of the Free Documentation License
19 as part of the file COPYING; also located in the main directory of the
20 source package of this program.
29 . nop \f[B]\[rs]\\*[@1]\f[]\\$*
37 . nop `\f[B]\\*[@1]\f[]'\\$*
46 .TH ROFF @MAN7EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
48 roff \- concepts and history of roff typesetting
56 is the general name for a set of text formatting programs, known under
65 system consists of an extensible text formatting language and a set of
66 programs for printing and converting to other text formats.
68 Unix-like operating systems distribute a
70 system as a core package.
75 system today is the free software implementation \f[CR]GNU\f[]
77 @T_ROFF@ is an deriviative.
78 Both implement the look-and-feel and functionality of its ancestors, with
84 is described in section
87 In this document, the term
89 always refers to the general class of roff programs, not to the
91 command provided in early UNIX systems.
96 is in wide use today, for example, the manual pages on UNIX systems
98 many software books, system documentation, standards, and corporate
99 documents are written in roff.
103 output for text devices is still unmatched, and its graphical output
104 has the same quality as other free type-setting programs and is better
105 than some of the commercial systems.
109 is used to format UNIX
113 the standard documentation system on many UNIX-derived operating systems.
116 This document describes the history of the development of the
118 some usage aspects common to all
120 versions, details on the
122 pipeline, which is usually hidden behind front-ends like
123 .BR @L_ROFF@ (@MAN1EXT@);
124 a general overview of the formatting language; some tips for editing
126 files; and many pointers to further readings.
133 Document formatting by computer dates back to the 1960s.
137 system itself is intimately connected to the Unix operating system, but its
138 roots go back to the earlier operating systems CTSS and Multics.
142 .SS "The Predecessor RUNOFF"
148 was written in the MAD language by
151 .IR "Compatible Time Sharing System (CTSS)" ,
152 a project of the Massachusetts Institute of Technology (MIT), in 1963 and
153 1964 \[en] note that CTSS commands were all uppercase.
156 In 1965, MIT's Project MAC teamed with Bell Telephone Laboratories (BTL)
157 and General Electric to begin the
158 .UR http://\:www.multicians.org
165 was written for Multics in the late 60s in the BCPL language, by
168 and other members of the Multics team.
171 Like its CTSS ancestor, Multics
173 formatted an input file consisting of text and command lines; commands began
174 with a period and were two letters.
176 Output from these commands was to terminal devices such as IBM Selectric
181 had additional features added, such as the ability to do two-pass
182 formatting; it became the main format for Multics documentation and text
188 were ported to the GCOS system at Bell Labs when BTL left the development of
193 .SS "The Classical nroff/troff System"
196 At BTL, there was a need to drive the
197 .I Graphic Systems CAT
198 typesetter, a graphical output device from a PDP-11 computer running Unix.
202 was too limited for this task it was further developed into a more
203 powerful text formatting system by
204 .IR "Joseph F.\& Ossanna" ,
205 who already programmed several runoff ports.
213 The greatly enlarged language of Ossanna's version already included all
219 systems try to implement compatibility to this system.
221 So Joe Ossanna can be called the father of all
228 had three formatter programs.
232 .RI ( "typesetter roff\/" )
233 generated a graphical output for the
235 typesetter as its only device.
239 produced text output suitable for terminals and line printers.
243 was the reimplementation of the former
245 program with its limited features; this program was abandoned in later
250 is used to refer to a
255 Ossanna's first version was written in the PDP-11 assembly language and
261 development by rewriting it in the C\~programming language.
263 The C\~version was released in 1975.
266 The syntax of the formatting language of the
268 programs was documented in the famous
269 .IR "Troff User's Manual [CSTR\~#54]" ,
270 first published in 1976, with further revisions up to 1992 by Brian
273 This document is the specification of the
274 .IR "classical troff" .
278 systems tried to establish compatibility with this specification.
281 After Ossanna's death in 1977, Kernighan went on with developing
284 In the late 1970s, Kernighan equipped
286 with a general interface to support more devices, the intermediate
287 output format, and the postprocessor system.
289 This completed the structure of a
291 as it is still in use today; see section
294 In 1979, these novelties were described in the paper
299 version is the basis for all existing newer troff systems, including
302 On some systems, this
303 .I device independent troff
304 got a binary of its own, called
305 .BR ditroff (@MAN7EXT@).
309 programs already provide the full
311 capabilities automatically.
318 The source code of both the ancient Unix and classical
320 weren't available for two decades.
322 Meanwhile, it is accessible again (on-line) for non-commercial use,
331 The most important free
333 project was the \f[CR]GNU\f[] implementation of
335 written from scratch by
338 .UR http://\:www.gnu.org/\:copyleft
347 Further forks exists.
349 .BR @L_ROFF@ (@MAN1EXT@)
352 It is compatible to the classical
354 but many extensions were added.
358 system that is available on almost all operating systems \[en] and it is
366 Most people won't even notice that they are actually using
369 When you read a system manual page (man page)
371 is working in the background.
376 implementations provide wrapper programs that make it easy to use the
378 system on the shell command line.
380 For example, the \f[CR]GNU\f[]
383 .BR groff (@MAN1EXT@)
384 provides command line options to avoid the long command pipes of
395 system consists of preprocessors,
397 formatter programs, and a set of device postprocessors.
399 This concept makes heavy use of the
401 mechanism, that is, a series of programs is called one after the other,
402 where the output of each program in the queue is taken as the input
403 for the next program.
409 | \f[I]preproc\f[P] \
411 | troff \f[I]options\f[P] \
416 The preprocessors generate
418 code that is fed into a
422 which in turn generates
423 .I intermediate output
424 that is fed into a device postprocessor program for printing or final
428 All of these parts use programming languages of their own; each
429 language is totally unrelated to the other parts.
433 macro packages that were tailored for special purposes can be
439 documents use the macros of some package, intermixed with code for one
440 or more preprocessors, spiced with some elements from the plain
444 The full power of the
446 formatting language is seldom needed by users; only programmers of
447 macro packages need to know about the gory details.
457 preprocessor is any program that generates output that syntactically
458 obeys the rules of the
462 Each preprocessor defines a language of its own that is translated
465 code when run through the preprocessor program.
467 Parts written in these languages may be included within a
469 document; they are identified by special
473 Each document that is enhanced by preprocessor code must be run
474 through all corresponding preprocessors before it is fed into the
477 formatter program, for the formatter just ignores all alien code.
479 The preprocessor programs extract and transform only the document
480 parts that are determined for them.
483 There are a lot of free and commercial
487 Some of them aren't available on each system, but there is a small
488 set of preprocessors that are considered as an integral part of each
492 The classical preprocessors are
499 eqn@for mathematical formul\[ae].
500 pic@for drawing diagrams.
501 refer@for bibliographic references.
502 soelim@for including macro files from standard locations.
503 chem@for drawing chemical formul\[ae].
508 Other known preprocessors that are not available on all systems
515 grap@for constructing graphical elements.
516 grn@for including \fBgremlin\fR(1) pictures.
521 .SS "Formatter Programs"
526 is a program that parses documents written in the
528 formatting language or uses some of the
533 .IR "intermediate output" ,
534 which is intended to be fed into a single device postprocessor that
535 must be specified by a command-line option to the formatter program.
537 The documents must have been run through all necessary preprocessors
541 The output produced by a
543 formatter is represented in yet another language, the
544 .IR "intermediate output format"
548 This language was first specified in
550 its @T_ROFF@ extension is documented in
551 .BR @L_ROFF@_out (@MAN5EXT@).
553 The intermediate output language is a kind of assembly language
554 compared to the high-level
558 The generated intermediate output is optimized for a special device,
559 but the language is the same for every device.
564 formatter is the heart of the
574 for graphical devices.
579 is used as a general term to refer to both formatters.
583 .SS "Devices and Postprocessors"
586 Devices are hardware interfaces like printers, text or graphical
587 terminals, etc., or software interfaces such as a conversion into a
588 different text or graphical format.
593 postprocessor is a program that transforms
595 output into a form suitable for a special device.
599 postprocessors are like device drivers for the output target.
602 For each device there is a postprocessor program that fits the device
605 The postprocessor parses the generated intermediate output and
606 generates device-specific code that is sent directly to the device.
609 The names of the devices and the postprocessor programs are not fixed
610 because they greatly depend on the software and hardware abilities of
613 For example, the classical devices mentioned in
615 have greatly changed since the classical times.
617 The old hardware doesn't exist any longer and the old graphical
618 conversions were quite imprecise when compared to their modern
622 For example, the Postscript device
626 had a resolution of 720 units per inch, while
629 device has 72000, a refinement of factor 100.
632 Today the operating systems provide device drivers for most
633 printer-like hardware, so it isn't necessary to write a special
634 hardware postprocessor for each printer.
638 .SH "ROFF PROGRAMMING"
643 are normal text files decorated by
649 formatting language is quite powerful; it is almost a full programming
650 language and provides elements to enlarge the language.
652 With these, it became possible to develop macro packages that are
653 tailored for special applications.
655 Such macro packages are much handier than plain
658 So most people will choose a macro package without worrying about the
668 Macro packages are collections of macros that are suitable to format a
669 special kind of documents in a convenient way.
671 This greatly eases the usage of
674 The macro definitions of a package are kept in a file called
680 All tmac files are stored in one or more directories at standardized
683 Details on the naming of macro packages and their placement is found
685 .BR @L_ROFF@_tmac (@MAN5EXT@).
688 A macro package that is to be used in a document can be announced to
689 the formatter by the command line option
692 .BR @L_TROFF@ (@MAN1EXT@),
693 or it can be specified within a document using the file inclusion
697 .BR @L_ROFF@ (@MAN7EXT@).
700 Famous classical macro packages are
702 for traditional man pages,
704 for \f[CR]BSD\f[]-style manual pages;
705 the macro sets for books, articles, and letters are
707 (probably from the first name of its creator
712 .IR "Manuscript Macros\/" ),
716 .IR "Memorandum Macros\/" ).
720 .SS "The roff Formatting Language"
725 formatting language is documented in the
726 .I Troff User's Manual
731 language is a full programming language providing requests, definition
732 of macros, escape sequences, string variables, number or size
733 registers, and flow controls.
737 are the predefined basic formatting commands similar to the commands
740 The user can define request-like elements using predefined
744 These are then called
747 A document writer will not note any difference in usage for requests
748 or macros; both are written on a line on their own starting with a dot.
754 elements starting with a backslash
757 They can be inserted anywhere, also in the midst of text in a line.
759 They are used to implement various features, including the insertion of
760 non-\f[CR]ASCII\f[] characters with
764 in-line comments with
766 the escaping of special control characters like
768 and many other features.
772 are variables that can store a string.
774 A string is stored by the
778 The stored string can be retrieved later by the
784 store numbers and sizes.
786 A register can be set with the request
788 and its value can be retrieved by the escape sequence
793 .SH "FILE NAME EXTENSIONS"
796 Manual pages (man pages) take the section number as a file name
797 extension, e.g., the filename for this document is
799 i.e., it is kept in section\~7
803 The classical macro packages take the package name as an extension, e.g.\&
805 for a document using the
821 But there is no general naming scheme for
827 is seen now and then.
829 Maybe there should be a standardization for the filename extensions of
834 File name extensions can be very handy in conjunction with the
838 It provides the possibility to feed all input into a command-line pipe
839 that is specified in the shell environment variable
842 This process is not well documented, so here an example:
847 LESSOPEN='|lesspipe %s'
854 is either a system supplied command or a shell script of your own.
861 The best program for editing a
863 document is Emacs (or Xemacs), see
868 mode that is suitable for all kinds of
872 This mode can be activated by the following methods.
875 When editing a file within Emacs the mode can be changed by typing
876 .RI ` "M-x nroff-mode" ',
879 means to hold down the
888 But it is also possible to have the mode automatically selected when
889 the file is loaded into the editor.
892 The most general method is to include the following 3 comment lines at
898 \&.\[rs]" Local Variables:
899 \&.\[rs]" mode: nroff
905 There is a set of file name extensions, e.g.\& the man pages that
906 trigger the automatic activation of the
911 Theoretically, it is possible to write the sequence
916 \&.\[rs]" \%-*-\ nroff\ -*-
921 as the first line of a file to have it started in
925 Unfortunately, some applications such as the
927 program are confused by this; so this is deprecated.
932 formatters provide automated line breaks and horizontal and vertical
935 In order to not disturb this, the following tips can be helpful.
938 Never include empty or blank lines in a
942 Instead, use the empty request (a line consisting of a dot only) or a
945 if a structuring element is needed.
948 Never start a line with whitespace because this can lead to
951 Indented paragraphs can be constructed in a controlled way by
956 Start each sentence on a line of its own, for the spacing after a dot
957 is handled differently depending on whether it terminates an
958 abbreviation or a sentence.
960 To distinguish both cases, do a line break after each sentence.
963 To additionally use the auto-fill mode in Emacs, it is best to insert
966 request (a line consisting of a dot only) after each sentence.
969 The following example shows how optimal
976 This is an example for a
980 This is the next sentence in the same paragraph.
982 This is a longer sentence stretching over several
983 lines; abbreviations like `cf.' are easily
984 identified because the dot is not followed by a
987 In the output, this will still go to the same
993 Besides Emacs, some other editors provide
995 style files too, e.g.\&
1006 There is a lot of documentation on
1009 The original papers on classical
1011 are still available, and all aspects of
1013 are documented in great detail.
1017 .SS "Internet sites"
1022 .UR http://\:www.troff.org
1023 The historical troff site
1025 provides an overview and pointers to all historical aspects of
1030 .UR http://\:www.multicians.org
1033 contains a lot of information on the MIT projects, CTSS, Multics,
1034 early Unix, including
1036 especially useful are a glossary and the many links to ancient
1041 .UR http://\:www.tuhs.org/\:Archive/
1042 The Ancient Unixes Archive
1045 provides the source code and some binaries of the ancient Unixes
1046 (including the source code of
1048 and its documentation) that were made public by Caldera since 2001,
1049 e.g.\& of the famous Unix version\~7 for PDP-11 at the
1050 .UR http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7
1055 Developers at AT&T Bell Labs
1056 .UR http://\:www.bell-labs.com/
1057 Bell Labs Computing and Mathematical Sciences Research
1060 provides a search facility for tracking information on the early
1065 .UR http://\:plan9.bell-labs.com
1066 The Plan\~9 operating system
1073 .UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
1074 Jerry Saltzer's home page
1077 stores some documents using the ancient RUNOFF formatting language.
1081 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html
1082 The Bell Labs CSTR site
1087 manuals (CSTR #54, #97, #114, #116, #122) and famous historical
1088 documents on programming.
1091 \f[CR]GNU\f[] \f[I]roff\f[]
1092 .UR http://\:www.gnu.org/\:software/\:groff
1093 The GNU troff web site
1102 .SS "Historical roff Documentation"
1107 documents are still available on-line.
1109 The two main manuals of the
1116 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
1117 .I "Nroff/\:Troff User's Manual"
1120 Bell Labs, 1976; revised by Brian Kernighan, 1992.
1125 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz
1126 .I "A Typesetter-independent TROFF"
1129 Bell Labs, 1981, revised March 1982.
1132 The \[lq]little language\[rq]
1138 Jon L. Bentley and Brian W. Kernighan,
1139 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:114.ps.gz
1140 .I "GRAP \[en] A Language for Typesetting Graphs"
1143 Bell Labs, August 1984.
1148 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz
1149 .I "PIC \[en] A Graphics Language for Typesetting"
1152 Bell Labs, December 1984.
1156 J. L. Bentley, L. W. Jelinski, and B. W. Kernighan,
1157 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
1158 .I "CHEM \[en] A Program for Typesetting Chemical Structure Diagrams,"
1159 .I "Computers and Chemistry"
1162 Bell Labs, April 1986.
1169 Due to its complex structure, a full
1171 system has many man pages, each describing a single aspect of
1174 Unfortunately, there is no general naming scheme for the documentation
1183 .BR @L_ROFF@ (@MAN1EXT@)
1184 contains a survey of all documentation available in
1188 On other systems, you are on your own, but
1189 .BR troff (@MAN1EXT@)
1190 might be a good starting point.
1197 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
1199 Copyright (C) 2000 - 2004, 2006 - 2008
1200 Free Software Foundation, Inc.
1203 This document is distributed under the terms of the \f[CR]FDL\f[]
1204 (\f[CR]GNU Free Documentation License\f[]) version 1.1 or later.
1206 You should have received a copy of the \f[CR]FDL\f[] on your system,
1207 it is also available on-line at the
1208 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1213 This document was written by