2 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
4 roff \- concepts and history of roff typesetting
6 .\" this is man-page roff.7
8 .\" --------------------------------------------------------------------
10 .\" --------------------------------------------------------------------
13 Copyright \[co] 2000-2014 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the FDL (GNU Free Documentation License) Version
17 1.3 or any later version published by the Free Software Foundation.
18 with the Invariant Sections being the .au and .co macro definitions,
19 with no Front-Cover Texts, and with no Back-Cover Texts.
21 A copy of the Free Documentation License is included as a file called
22 FDL in the main directory of the groff source package.
24 The license text is also available on-line at the
25 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
31 This man-page was written by
32 .MT groff-bernd.warken-72@web.de
41 .\" --------------------------------------------------------------------
47 . nop \f[B]\[rs]\\*[@1]\f[]\\$*
55 . nop \[oq]\f[B]\\*[@1]\f[]\[cq]\\$*
59 .\" --------------------------------------------------------------------
61 .\" --------------------------------------------------------------------
64 is the general name for a set of text formatting programs, known under
74 system consists of an extensible text formatting language and a set of
75 programs for printing and converting to other text formats.
77 Unix-like operating systems distribute a
79 system as a core package.
85 system today is the free software implementation \f[CR]GNU\f[]
87 .BR groff (@MAN1EXT@).
90 implements the look-and-feel and functionality of its ancestors, with many
97 is described in section
100 In this document, the term
102 always refers to the general class of roff programs, not to the
104 command provided in early UNIX systems.
110 is in wide use today, for example, the manual pages on UNIX systems
112 many software books, system documentation, standards, and corporate
113 documents are written in roff.
117 output for text devices is still unmatched, and its graphical output
118 has the same quality as other free type-setting programs and is better
119 than some of the commercial systems.
124 is used to format UNIX
128 the standard documentation system on many UNIX-derived operating systems.
132 This document describes the history of the development of the
134 some usage aspects common to all
136 versions, details on the
138 pipeline, which is usually hidden behind front-ends like
139 .BR groff (@MAN1EXT@);
140 a general overview of the formatting language; some tips for editing
142 files; and many pointers to further readings.
145 .\" --------------------------------------------------------------------
147 .\" --------------------------------------------------------------------
149 Document formatting by computer dates back to the 1960s.
153 system itself is intimately connected to the Unix operating system, but its
154 roots go back to the earlier operating systems CTSS and Multics.
157 .\" --------------------------------------------------------------------
158 .SS "The Predecessor RUNOFF"
159 .\" --------------------------------------------------------------------
164 was written in the MAD language by
167 .IR "Compatible Time Sharing System (CTSS)" ,
168 a project of the Massachusetts Institute of Technology (MIT), in 1963 and
169 1964 \[en] note that CTSS commands were all uppercase.
172 In 1965, MIT\[aq]s Project MAC teamed with Bell Telephone Laboratories
173 (BTL) and General Electric to begin the
174 .UR http://\:www.multicians.org
181 was written for Multics in the late 60s in the BCPL language, by
184 and other members of the Multics team.
188 Like its CTSS ancestor, Multics
190 formatted an input file consisting of text and command lines; commands began
191 with a period and were two letters.
193 Output from these commands was to terminal devices such as IBM Selectric
198 had additional features added, such as the ability to do two-pass
199 formatting; it became the main format for Multics documentation and text
206 were ported to the GCOS system at Bell Labs when BTL left the development of
211 There is a free archive about
215 You can get it anonymously by the shell command
218 $git clone https://github.com/bwarken/RUNOFF_historical.git
224 As well, there is a new project for writing a program that can read
226 but it does not yet work so far.
228 You can get an early version anonymously by the shell command
231 $git clone https://github.com/bwarken/runoff.git
236 .\" --------------------------------------------------------------------
237 .SS "The Classical nroff/troff System"
238 .\" --------------------------------------------------------------------
240 At BTL, there was a need to drive the
241 .I Graphic Systems CAT
242 typesetter, a graphical output device from a PDP-11 computer running Unix.
246 was too limited for this task it was further developed into a more
247 powerful text formatting system by
248 .IR "Joseph F.\& Ossanna" ,
249 who already programmed several runoff ports.
258 The greatly enlarged language of Ossanna\[aq]s version already
259 included all elements of a full
264 systems try to implement compatibility to this system.
266 So Joe Ossanna can be called the father of all
274 had three formatter programs.
278 .RI ( "typesetter roff\/" )
279 generated a graphical output for the
281 typesetter as its only device.
285 produced text output suitable for terminals and line printers.
289 was the reimplementation of the former
291 program with its limited features; this program was abandoned in later
296 is used to refer to a
302 Ossanna\[aq]s first version was written in the PDP-11 assembly
303 language and released in 1973.
308 development by rewriting it in the C\~programming language.
310 The C\~version was released in 1975.
314 The syntax of the formatting language of the
316 programs was documented in the famous
317 .IR "Troff User\[aq]s Manual [CSTR\~#54]" ,
318 first published in 1976, with further revisions up to 1992 by Brian
321 This document is the specification of the
322 .IR "classical troff" .
326 systems tried to establish compatibility with this specification.
330 After Ossanna\[aq]s death in 1977, Kernighan went on with developing
333 In the late 1970s, Kernighan equipped
335 with a general interface to support more devices, the intermediate
336 output format, and the postprocessor system.
338 This completed the structure of a
340 as it is still in use today; see section
343 In 1979, these novelties were described in the paper
348 version is the basis for all existing newer troff systems, including
351 On some systems, this
352 .I device independent troff
353 got a binary of its own, called
354 .BR ditroff (@MAN7EXT@).
358 programs already provide the full
360 capabilities automatically.
363 .\" --------------------------------------------------------------------
365 .\" --------------------------------------------------------------------
367 The source code of both the ancient Unix and classical
369 weren\[aq]t available for two decades.
371 Meanwhile, it is accessible again (on-line) for non-commercial use,
376 .\" --------------------------------------------------------------------
377 .SS "groff \[em] free GNU roff"
378 .\" --------------------------------------------------------------------
380 The most important free
382 project was the \f[CR]GNU\f[] implementation of
384 written from scratch by
387 .UR http://\:www.gnu.org/\:copyleft
397 .BR groff (@MAN1EXT@)
404 system is still actively developed.
406 It is compatible to the classical
408 but many extensions were added.
412 system that is available on almost all operating systems \[em] and it
422 .\" --------------------------------------------------------------------
423 .SS "Free Heirloom roff"
424 .\" --------------------------------------------------------------------
427 .UR https://\:github.com/\:n-t-roff/\:heirloom-doctools
428 .I Gunnar Ritter\[aq]s Heirloom roff project
430 project, started in 2005, which provides enhanced versions of the various
431 roff tools found in the OpenSolaris and Plan\~9 operating systems, now
432 available under free licenses.
434 You can get this package with the shell command:
437 \[Do] git clone https://github.com/n-t-roff/heirloom-doctools
443 Moreover, one finds there the
444 .UR https://github.com/n-t-roff/DWB3.3
445 .I Original Documenter\[aq]s Workbench Release 3.3
449 .\" --------------------------------------------------------------------
451 .\" --------------------------------------------------------------------
453 Most people won\[aq]t even notice that they are actually using
456 When you read a system manual page (man page)
458 is working in the background.
461 documents can be viewed with a native viewer called
463 a standard program of the X window distribution, see
468 explicitly isn\[aq]t difficult either.
474 implementations provide wrapper programs that make it easy to use the
476 system on the shell command line.
478 For example, the \f[CR]GNU\f[]
481 .BR groff (@MAN1EXT@)
482 provides command line options to avoid the long command pipes of
487 tries to guess from the document which arguments should be used for a
490 people who do not like specifying command line options should try the
491 .BR groffer (@MAN1EXT@)
492 program for graphically displaying
497 .\" --------------------------------------------------------------------
499 .\" --------------------------------------------------------------------
503 system consists of preprocessors,
505 formatter programs, and a set of device postprocessors.
507 This concept makes heavy use of the
509 mechanism, that is, a series of programs is called one after the other,
510 where the output of each program in the queue is taken as the input
511 for the next program.
517 | \f[I]preproc\f[P] \
519 | troff \f[I]options\f[P] \
525 The preprocessors generate
527 code that is fed into a
531 which in turn generates
532 .I intermediate output
533 that is fed into a device postprocessor program for printing or final
538 All of these parts use programming languages of their own; each
539 language is totally unrelated to the other parts.
543 macro packages that were tailored for special purposes can be
550 documents use the macros of some package, intermixed with code for one
551 or more preprocessors, spiced with some elements from the plain
555 The full power of the
557 formatting language is seldom needed by users; only programmers of
558 macro packages need to know about the gory details.
562 .\" --------------------------------------------------------------------
564 .\" --------------------------------------------------------------------
568 preprocessor is any program that generates output that syntactically
569 obeys the rules of the
573 Each preprocessor defines a language of its own that is translated
576 code when run through the preprocessor program.
578 Parts written in these languages may be included within a
580 document; they are identified by special
584 Each document that is enhanced by preprocessor code must be run
585 through all corresponding preprocessors before it is fed into the
588 formatter program, for the formatter just ignores all alien code.
590 The preprocessor programs extract and transform only the document
591 parts that are determined for them.
595 There are a lot of free and commercial
599 Some of them aren\[aq]t available on each system, but there is a small
600 set of preprocessors that are considered as an integral part of each
604 The classical preprocessors are
611 eqn@for mathematical formulae.
612 pic@for drawing diagrams.
613 refer@for bibliographic references.
614 soelim@for including macro files from standard locations.
615 chem@for drawing chemical formul\[ae].
621 Other known preprocessors that are not available on all systems
628 grap@for constructing graphical elements.
629 grn@for including \fBgremlin\fR(1) pictures.
634 .\" --------------------------------------------------------------------
635 .SS "Formatter Programs"
636 .\" --------------------------------------------------------------------
640 is a program that parses documents written in the
642 formatting language or uses some of the
647 .IR "intermediate output" ,
648 which is intended to be fed into a single device postprocessor that
649 must be specified by a command-line option to the formatter program.
651 The documents must have been run through all necessary preprocessors
656 The output produced by a
658 formatter is represented in yet another language, the
659 .IR "intermediate output format"
663 This language was first specified in
665 its \f[CR]GNU\f[] extension is documented in
666 .BR groff_out (@MAN5EXT@).
668 The intermediate output language is a kind of assembly language
669 compared to the high-level
673 The generated intermediate output is optimized for a special device,
674 but the language is the same for every device.
680 formatter is the heart of the
690 for graphical devices.
696 is used as a general term to refer to both formatters.
699 .\" --------------------------------------------------------------------
700 .SS "Devices and Postprocessors"
701 .\" --------------------------------------------------------------------
703 Devices are hardware interfaces like printers, text or graphical
704 terminals, etc., or software interfaces such as a conversion into a
705 different text or graphical format.
711 postprocessor is a program that transforms
713 output into a form suitable for a special device.
717 postprocessors are like device drivers for the output target.
721 For each device there is a postprocessor program that fits the device
724 The postprocessor parses the generated intermediate output and
725 generates device-specific code that is sent directly to the device.
729 The names of the devices and the postprocessor programs are not fixed
730 because they greatly depend on the software and hardware abilities of
733 For example, the classical devices mentioned in
735 have greatly changed since the classical times.
737 The old hardware doesn\[aq]t exist any longer and the old graphical
738 conversions were quite imprecise when compared to their modern
743 For example, the Postscript device
747 had a resolution of 720 units per inch, while
750 device has 72000, a refinement of factor 100.
754 Today the operating systems provide device drivers for most
755 printer-like hardware, so it isn\[aq]t necessary to write a special
756 hardware postprocessor for each printer.
759 .\" --------------------------------------------------------------------
760 .SH "ROFF PROGRAMMING"
761 .\" --------------------------------------------------------------------
765 are normal text files decorated by
771 formatting language is quite powerful; it is almost a full programming
772 language and provides elements to enlarge the language.
774 With these, it became possible to develop macro packages that are
775 tailored for special applications.
777 Such macro packages are much handier than plain
780 So most people will choose a macro package without worrying about the
786 .\" --------------------------------------------------------------------
788 .\" --------------------------------------------------------------------
790 Macro packages are collections of macros that are suitable to format a
791 special kind of documents in a convenient way.
793 This greatly eases the usage of
796 The macro definitions of a package are kept in a file called
802 All tmac files are stored in one or more directories at standardized
805 Details on the naming of macro packages and their placement is found
807 .BR groff_tmac (@MAN5EXT@).
811 A macro package that is to be used in a document can be announced to
812 the formatter by the command line option
815 .BR troff (@MAN1EXT@),
816 or it can be specified within a document using the file inclusion
820 .BR groff (@MAN7EXT@).
824 Famous classical macro packages are
826 for traditional man pages,
828 for \f[CR]BSD\f[]-style manual pages;
829 the macro sets for books, articles, and letters are
831 (probably from the first name of its creator
836 .IR "Manuscript Macros\/" ),
840 .IR "Memorandum Macros\/" ).
843 .\" --------------------------------------------------------------------
844 .SS "The roff Formatting Language"
845 .\" --------------------------------------------------------------------
849 formatting language is documented in the
850 .I Troff User\[aq]s Manual
855 language is a full programming language providing requests, definition
856 of macros, escape sequences, string variables, number or size
857 registers, and flow controls.
862 are the predefined basic formatting commands similar to the commands
865 The user can define request-like elements using predefined
869 These are then called
872 A document writer will not note any difference in usage for requests
873 or macros; both are written on a line on their own starting with a dot.
880 elements starting with a backslash
883 They can be inserted anywhere, also in the midst of text in a line.
885 They are used to implement various features, including the insertion of
886 non-\f[CR]ASCII\f[] characters with
890 in-line comments with
892 the escaping of special control characters like
894 and many other features.
899 are variables that can store a string.
901 A string is stored by the
905 The stored string can be retrieved later by the
912 store numbers and sizes.
914 A register can be set with the request
916 and its value can be retrieved by the escape sequence
920 .\" --------------------------------------------------------------------
921 .SH "FILE NAME EXTENSIONS"
922 .\" --------------------------------------------------------------------
924 Manual pages (man pages) take the section number as a file name
925 extension, e.g., the filename for this document is
927 i.e., it is kept in section\~7
932 The classical macro packages take the package name as an extension, e.g.\&
934 for a document using the
951 But there is no general naming scheme for
957 is seen now and then.
959 Maybe there should be a standardization for the filename extensions of
965 File name extensions can be very handy in conjunction with the
969 It provides the possibility to feed all input into a command-line pipe
970 that is specified in the shell environment variable
973 This process is not well documented, so here an example:
978 LESSOPEN='|lesspipe %s'
986 is either a system supplied command or a shell script of your own.
991 .I file name extensions
993 .BR groff_filenames (7).
996 .\" --------------------------------------------------------------------
998 .\" --------------------------------------------------------------------
1000 The best program for editing a
1002 document is Emacs (or Xemacs), see
1007 mode that is suitable for all kinds of
1011 This mode can be activated by the following methods.
1015 When editing a file within Emacs the mode can be changed by typing
1016 .RI \[oq] "M-x nroff-mode" \[cq],
1019 means to hold down the
1029 But it is also possible to have the mode automatically selected when
1030 the file is loaded into the editor.
1033 The most general method is to include the following 3 comment lines at
1034 the end of the file.
1039 \&.\[rs]" Local Variables:\""
1040 \&.\[rs]" mode: nroff\""
1046 There is a set of file name extensions, e.g.\& the man pages that
1047 trigger the automatic activation of the
1052 Theoretically, it is possible to write the sequence
1057 \&.\[rs]" \%-*-\ nroff\ -*-\""
1062 as the first line of a file to have it started in
1066 Unfortunately, some applications such as the
1068 program are confused by this; so this is deprecated.
1074 formatters provide automated line breaks and horizontal and vertical
1077 In order to not disturb this, the following tips can be helpful.
1080 Never include empty or blank lines in a
1084 Instead, use the empty request (a line consisting of a dot only) or a
1087 if a structuring element is needed.
1090 Never start a line with whitespace because this can lead to unexpected
1093 Indented paragraphs can be constructed in a controlled way by
1098 Start each sentence on a line of its own, for the spacing after a dot
1099 is handled differently depending on whether it terminates an
1100 abbreviation or a sentence.
1102 To distinguish both cases, do a line break after each sentence.
1105 To additionally use the auto-fill mode in Emacs, it is best to insert
1108 request (a line consisting of a dot only) after each sentence.
1112 The following example shows how optimal
1119 This is an example for a \&.I roff document. \&.
1121 This is the next sentence in the same paragraph. \&.
1123 This is a longer sentence stretching over several lines; abbreviations
1124 like \[oq]cf.\[cq] are easily identified because the dot is not
1125 followed by a line break. \&. In the output, this will still go to
1132 Besides Emacs, some other editors provide
1134 style files too, e.g.\&
1141 .\" --------------------------------------------------------------------
1143 .\" --------------------------------------------------------------------
1145 There is a lot of documentation on
1148 The original papers on classical
1150 are still available, and all aspects of
1152 are documented in great detail.
1155 .\" --------------------------------------------------------------------
1156 .SS "Internet sites"
1157 .\" --------------------------------------------------------------------
1161 .UR http://\:www.troff.org
1162 The historical troff site
1164 provides an overview and pointers to all historical aspects of
1169 .UR http://\:www.multicians.org
1172 contains a lot of information on the MIT projects, CTSS, Multics,
1173 early Unix, including
1175 especially useful are a glossary and the many links to ancient
1180 .UR http://\:www.tuhs.org/\:Archive/
1181 The Ancient Unixes Archive
1184 provides the source code and some binaries of the ancient Unixes
1185 (including the source code of
1187 and its documentation) that were made public by Caldera since 2001,
1188 e.g.\& of the famous Unix version\~7 for PDP-11 at the
1189 .UR http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7
1194 Developers at AT&T Bell Labs
1195 .UR http://\:www.bell-labs.com/
1196 Bell Labs Computing and Mathematical Sciences Research
1199 provides a search facility for tracking information on the early
1204 .UR http://\:plan9.bell-labs.com
1205 The Plan\~9 operating system
1212 .UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
1213 Jerry Saltzer\[aq]s home page
1216 stores some documents using the ancient RUNOFF formatting language.
1220 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html
1221 The Bell Labs CSTR site
1226 manuals (CSTR #54, #97, #114, #116, #122) and famous historical
1227 documents on programming.
1230 \f[CR]GNU\f[] \f[I]roff\f[]
1231 .UR http://\:www.gnu.org/\:software/\:groff
1242 .\" --------------------------------------------------------------------
1243 .SS "Historical roff Documentation"
1244 .\" --------------------------------------------------------------------
1248 documents are still available on-line.
1250 The two main manuals of the
1257 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
1258 .I "Nroff/\:Troff User\[aq]s Manual"
1261 Bell Labs, 1976; revised by Brian Kernighan, 1992.
1266 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz
1267 .I "A Typesetter-independent TROFF"
1270 Bell Labs, 1981, revised March 1982.
1273 The \[lq]little language\[rq]
1279 Jon L.\& Bentley and Brian W.\& Kernighan,
1280 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:114.ps.gz
1281 .I "GRAP \[en] A Language for Typesetting Graphs"
1284 Bell Labs, August 1984.
1288 Brian W.\& Kernighan,
1289 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz
1290 .I "PIC \[en] A Graphics Language for Typesetting"
1293 Bell Labs, December 1984.
1297 J.\& L.\& Bentley, L.\& W.\& Jelinski, and B.\& W.\& Kernighan,
1298 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
1299 .I "CHEM \[en] A Program for Typesetting Chemical Structure Diagrams,"
1300 .I "Computers and Chemistry"
1303 Bell Labs, April 1986.
1307 You can get an archive with most
1308 .I classical roff documentation
1317 $ git clone https://github.com/bwarken/roff_classical.git
1322 .\" --------------------------------------------------------------------
1324 .\" --------------------------------------------------------------------
1326 Due to its complex structure, a full
1328 system has many man pages, each describing a single aspect of
1331 Unfortunately, there is no general naming scheme for the documentation
1341 .BR groff (@MAN1EXT@)
1342 contains a survey of all documentation available in
1347 On other systems, you are on your own, but
1349 might be a good starting point.
1352 .\" --------------------------------------------------------------------
1354 .\" --------------------------------------------------------------------
1356 .\" --------------------------------------------------------------------
1358 .\" --------------------------------------------------------------------
1362 .\" --------------------------------------------------------------------
1364 .\" --------------------------------------------------------------------
1366 .\" Local Variables: