5 Last update: 02 Feb 2007
7 This file is part of groff, the GNU roff type-setting system.
9 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007
10 Free Software Foundation, Inc.
11 written by Bernd Warken <bwarken@mayn.de>
12 maintained by Werner Lemberg <wl@gnu.org>
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.1 or
16 any later version published by the Free Software Foundation; with the
17 Invariant Sections being this .ig-section and AUTHORS, with no
18 Front-Cover Texts, and with no Back-Cover Texts.
20 A copy of the Free Documentation License is included as a file called
21 FDL in the main directory of the groff source package.
25 .\" --------------------------------------------------------------------
31 . nop \f[B]\[rs]\\*[@1]\f[]\\$*
39 . nop `\f[B]\\*[@1]\f[]'\\$*
44 .\" --------------------------------------------------------------------
46 .\" --------------------------------------------------------------------
48 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
50 roff \- concepts and history of roff typesetting
53 .\" --------------------------------------------------------------------
55 .\" --------------------------------------------------------------------
58 is the general name for a set of type-setting programs, known under
68 type-setting system consists of an extensible text formatting language
69 and a set of programs for printing and converting to other text
72 Traditionally, it is the main text processing system of Unix; every
73 Unix-like operating system still distributes a
75 system as a core package.
80 system today is the free software implementation \f[CR]GNU\f[]
82 .BR groff (@MAN1EXT@).
86 implementations are referred to as
88 (dating back as long as 1973).
91 implements the look-and-feel and functionality of its classical
92 ancestors, but has many extensions.
95 In some ancient Unix systems, there was a binary called
97 that implemented the even more ancient
101 operating system, cf.\& section
103 The functionality of this program was very restricted even in
104 comparison to ancient
106 it is not supported any longer.
108 Consequently, in this document, the term
110 always refers to the general meaning of
119 is in wide use today, for example, the manual pages on UNIX systems
120 .RI ( man\~pages\/ ),
121 many software books, system documentation, standards, and corporate
122 documents are written in roff.
126 output for text devices is still unmatched, and its graphical output
127 has the same quality as other free type-setting programs and is better
128 than some of the commercial systems.
131 The most popular application of
137 this is the standard documentation system on many operating systems.
140 This document describes the historical facts around the development
143 some usage aspects common to all
145 versions, details on the
147 pipeline, which is usually hidden behind front-ends like
148 .BR groff (@MAN1EXT@);
149 a general overview of the formatting language; some tips for editing
151 files; and many pointers to further readings.
154 .\" --------------------------------------------------------------------
156 .\" --------------------------------------------------------------------
160 text processing system has a very long history, dating back to the
165 system itself is intimately connected to the Unix operating system,
166 but its roots go back to the earlier operating systems CTSS and
170 .\" --------------------------------------------------------------------
171 .SS "The Predecessor RUNOFF"
172 .\" --------------------------------------------------------------------
177 is intimately related to the history of the operating systems.
186 .RI ( "Compatible Time Sharing System" )
187 as early as 1964 \[en] note that CTSS commands were all uppercase.
189 When CTSS was further developed into the operating system
190 .UR http://\:www.multicians.org ,
193 the famous predecessor of Unix from 1963,
195 has been improved further by people from the Massachusetts Institute of
196 Technology (MIT) and the Bell Technical Laboratory (BTL), including Dennis
197 Ritchie and Joe Ossanna.
199 .BR "Multics runoff" ,
200 for example, was now able to do two-pass operations; it became the main
201 format for documentation and text processing.
203 Both operating systems could only be run on very expensive computers
204 at that time, so they were mostly used in research and for official
208 The possibilities of the
210 language were quite limited as compared to modern
213 Only text output was possible in the 1960s.
215 This could be implemented by a set of requests of length\~2, many of
216 which are still identically used in
219 The language was modelled according to the habits of typesetting in
220 the pre-computer age, where lines starting with a dot were used in
221 manuscripts to denote formatting requests to the person who would
222 perform the typesetting manually later on.
225 The runoff program was written in the
227 language first, later on in
229 the grandmother of the
231 programming language.
233 In the Multics operating system, the help system was handled by
236 task to manage the Unix manual pages.
238 On the other hand, BCPL and runoff were ported to the GCOS system
239 at Bell Labs since BTL left the development of Multics.
242 There are still documents written in the RUNOFF language; for examples
243 see Saltzer's home page, cf.\& section
247 .\" --------------------------------------------------------------------
248 .SS "The Classical nroff/troff System"
249 .\" --------------------------------------------------------------------
251 At the Bell Labs, there was a need to
253 .I Graphic Systems CAT
254 typesetter, a graphical output device from a PDP-11 computer running
257 As runoff was too limited for this task it was further developed into
258 a more powerful text formatting system by
259 .IR "Josef F. Osanna" ,
260 who already programmed several runoff ports.
267 The greatly enlarged language of Osanna's concept included already all
273 systems try to implement compatibility to this system.
275 So Joe Osanna can be called the father of all
282 had three formatter programs.
286 .RI ( "typesetter roff\/" )
287 generated a graphical output for the
289 typesetter as its only device.
293 produced text output suitable for terminals and line printers.
297 was the reimplementation of the former
299 program with its limited features; this program was abandoned in later
304 is used to refer to a
309 Osanna's first version was written in the PDP-11 assembly language and
315 development by rewriting it in the C\~programming language.
317 The C\~version was released in 1975.
320 The syntax of the formatting language of the
322 programs was documented in the famous
323 .IR "Troff User's Manual [CSTR\~#54]" ,
324 first published in 1976, with further revisions up to 1992 by Brian
327 This document is the specification of the
328 .IR "classical troff" .
331 systems tried to establish compatibility with this specification.
334 After Osanna had died in 1977 by a heart-attack at the age of about\~50,
335 Kernighan went on with developing
338 The next milestone was to equip
340 with a general interface to support more devices, the intermediate
341 output format and the postprocessor system.
343 This completed the structure of a
345 as it is still in use today; see section
348 In 1979, these novelties were described in the paper
352 version is the basis for all existing newer
357 On some systems, this
358 .I device independent troff
359 got a binary of its own, called
360 .BR ditroff (@MAN7EXT@).
364 programs already provide the full
366 capabilities automatically.
369 .\" --------------------------------------------------------------------
370 .SS "Commercialization"
371 .\" --------------------------------------------------------------------
373 A major degradation occurred when the easily available Unix\~7
374 operating system was commercialized.
376 A whole bunch of divergent operating systems emerged, fighting each
377 other with incompatibilities in their extensions.
379 Luckily, the incompatibilities did not fight the original
382 All of the different commercial
384 systems made heavy use of Osanna/\:Kernighan's open source code and
385 documentation, but sold them as \[lq]their\[rq] system \[en] with only
389 The source code of both the ancient Unix and classical
391 weren't available for two decades.
393 Fortunately, Caldera bought SCO UNIX in 2001.
395 In the following, Caldera made the ancient source code accessible
396 on-line for non-commercial use, cf. section
400 .\" --------------------------------------------------------------------
402 .\" --------------------------------------------------------------------
404 The most important free
406 project was the \f[CR]GNU\f[] implementation of
408 written from scratch by James Clark and put under the
409 .UR http://\:www.gnu.org/\:copyleft .
418 .BR groff (@MAN1EXT@)
424 system is still actively developed.
426 It is compatible to the classical
428 but many extensions were added.
432 system that is available on almost all operating systems \[en] and it
442 An alternative is Gunnar Ritter's
443 .UR http://\:heirloom.sf.net
444 Heirloom Documentation Tools
446 project, started in 2005, which provides enhanced versions of the various
447 roff tools found in the OpenSolaris and Plan\~9 operating systems, now
448 available under free licenses.
451 .\" --------------------------------------------------------------------
453 .\" --------------------------------------------------------------------
455 Most people won't even notice that they are actually using
458 When you read a system manual page (man page)
460 is working in the background.
463 documents can be viewed with a native viewer called
465 a standard program of the X window distribution, see
470 explicitly isn't difficult either.
475 implementations provide wrapper programs that make it easy to use the
477 system on the shell command line.
479 For example, the \f[CR]GNU\f[]
482 .BR groff (@MAN1EXT@)
483 provides command line options to avoid the long command pipes of
488 tries to guess from the document which arguments should be used for a
491 people who do not like specifying command line options should try the
492 .BR groffer (@MAN1EXT@)
493 program for graphically displaying
498 .\" --------------------------------------------------------------------
500 .\" --------------------------------------------------------------------
504 system consists of preprocessors,
506 formatter programs, and a set of device postprocessors.
508 This concept makes heavy use of the
510 mechanism, that is, a series of programs is called one after the other,
511 where the output of each program in the queue is taken as the input
512 for the next program.
518 | \f[I]preproc\f[P] \
520 | 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
537 All of these parts use programming languages of their own; each
538 language is totally unrelated to the other parts.
542 macro packages that were tailored for special purposes can be
548 documents use the macros of some package, intermixed with code for one
549 or more preprocessors, spiced with some elements from the plain
553 The full power of the
555 formatting language is seldom needed by users; only programmers of
556 macro packages need to know about the gory details.
560 .\" --------------------------------------------------------------------
562 .\" --------------------------------------------------------------------
566 preprocessor is any program that generates output that syntactically
567 obeys the rules of the
571 Each preprocessor defines a language of its own that is translated
574 code when run through the preprocessor program.
576 Parts written in these languages may be included within a
578 document; they are identified by special
582 Each document that is enhanced by preprocessor code must be run
583 through all corresponding preprocessors before it is fed into the
586 formatter program, for the formatter just ignores all alien code.
588 The preprocessor programs extract and transform only the document
589 parts that are determined for them.
592 There are a lot of free and commercial
596 Some of them aren't available on each system, but there is a small
597 set of preprocessors that are considered as an integral part of each
601 The classical preprocessors are
608 eqn@for mathematical formul\[ae].
609 pic@for drawing diagrams.
610 refer@for bibliographic references.
611 soelim@for including macro files from standard locations.
612 chem@for drawing chemical formul\[ae].
617 Other known preprocessors that are not available on all systems
624 grap@for constructing graphical elements.
625 grn@for including \fBgremlin\fR(1) pictures.
629 .\" --------------------------------------------------------------------
630 .SS "Formatter Programs"
631 .\" --------------------------------------------------------------------
635 is a program that parses documents written in the
637 formatting language or uses some of the
642 .IR "intermediate output" ,
643 which is intended to be fed into a single device postprocessor that
644 must be specified by a command-line option to the formatter program.
646 The documents must have been run through all necessary preprocessors
650 The output produced by a
652 formatter is represented in yet another language, the
653 .IR "intermediate output format"
656 This language was first specified in
658 its \f[CR]GNU\f[] extension is documented in
659 .BR groff_out (@MAN5EXT@).
661 The intermediate output language is a kind of assembly language
662 compared to the high-level
666 The generated intermediate output is optimized for a special device,
667 but the language is the same for every device.
672 formatter is the heart of the
682 for graphical devices.
687 is used as a general term to refer to both formatters.
690 .\" --------------------------------------------------------------------
691 .SS "Devices and Postprocessors"
692 .\" --------------------------------------------------------------------
694 Devices are hardware interfaces like printers, text or graphical
695 terminals, etc., or software interfaces such as a conversion into a
696 different text or graphical format.
701 postprocessor is a program that transforms
703 output into a form suitable for a special device.
707 postprocessors are like device drivers for the output target.
710 For each device there is a postprocessor program that fits the device
713 The postprocessor parses the generated intermediate output and
714 generates device-specific code that is sent directly to the device.
717 The names of the devices and the postprocessor programs are not fixed
718 because they greatly depend on the software and hardware abilities of
721 For example, the classical devices mentioned in
723 have greatly changed since the classical times.
725 The old hardware doesn't exist any longer and the old graphical
726 conversions were quite imprecise when compared to their modern
730 For example, the Postscript device
734 had a resolution of 720, while
737 device has 72000, a refinement of factor 100.
740 Today the operating systems provide device drivers for most
741 printer-like hardware, so it isn't necessary to write a special
742 hardware postprocessor for each printer.
745 .\" --------------------------------------------------------------------
746 .SH "ROFF PROGRAMMING"
747 .\" --------------------------------------------------------------------
751 are normal text files decorated by
757 formatting language is quite powerful; it is almost a full programming
758 language and provides elements to enlarge the language.
760 With these, it became possible to develop macro packages that are
761 tailored for special applications.
763 Such macro packages are much handier than plain
766 So most people will choose a macro package without worrying about the
772 .\" --------------------------------------------------------------------
774 .\" --------------------------------------------------------------------
776 Macro packages are collections of macros that are suitable to format a
777 special kind of documents in a convenient way.
779 This greatly eases the usage of
782 The macro definitions of a package are kept in a file called
788 All tmac files are stored in one or more directories at standardized
791 Details on the naming of macro packages and their placement is found
793 .BR groff_tmac (@MAN5EXT@).
796 A macro package that is to be used in a document can be announced to
797 the formatter by the command line option
800 .BR troff (@MAN1EXT@),
801 or it can be specified within a document using the file inclusion
805 .BR groff (@MAN7EXT@).
808 Famous classical macro packages are
810 for traditional man pages,
812 for \f[CR]BSD\f[]-style manual pages;
813 the macro sets for books, articles, and letters are
815 (probably from the first name of its creator
820 .IR "Manuscript Macros\/" ),
824 .IR "Memorandum Macros\/" ).
827 .\" --------------------------------------------------------------------
828 .SS "The roff Formatting Language"
829 .\" --------------------------------------------------------------------
833 formatting language is documented in the
834 .I Troff User's Manual
839 language is a full programming language providing requests, definition
840 of macros, escape sequences, string variables, number or size
841 registers, and flow controls.
845 are the predefined basic formatting commands similar to the commands
848 The user can define request-like elements using predefined
852 These are then called
855 A document writer will not note any difference in usage for requests
856 or macros; both are written on a line on their own starting with a dot.
862 elements starting with a backslash
864 They can be inserted anywhere, also in the midst of text in a line.
866 They are used to implement various features, including the insertion of
867 non-\f[CR]ASCII\f[] characters with
871 in-line comments with
873 the escaping of special control characters like
875 and many other features.
879 are variables that can store a string.
881 A string is stored by the
885 The stored string can be retrieved later by the
891 store numbers and sizes.
893 A register can be set with the request
895 and its value can be retrieved by the escape sequence
899 .\" --------------------------------------------------------------------
900 .SH "FILE NAME EXTENSIONS"
901 .\" --------------------------------------------------------------------
903 Manual pages (man pages) take the section number as a file name
904 extension, e.g., the filename for this document is
906 i.e., it is kept in section\~7
910 The classical macro packages take the package name as an extension, e.g.\&
912 for a document using the
928 But there is no general naming scheme for
934 is seen now and then.
936 Maybe there should be a standardization for the filename extensions of
941 File name extensions can be very handy in conjunction with the
945 It provides the possibility to feed all input into a command-line pipe
946 that is specified in the shell environment variable
948 This process is not well documented, so here an example:
953 LESSOPEN='|lesspipe %s'
960 is either a system supplied command or a shell script of your own.
963 .\" --------------------------------------------------------------------
965 .\" --------------------------------------------------------------------
967 The best program for editing a
969 document is Emacs (or Xemacs), see
973 mode that is suitable for all kinds of
977 This mode can be activated by the following methods.
980 When editing a file within Emacs the mode can be changed by typing
981 .RI ` "M-x nroff-mode" ',
984 means to hold down the
993 But it is also possible to have the mode automatically selected when
994 the file is loaded into the editor.
997 The most general method is to include the following 3 comment lines at
1003 \&.\[rs]" Local Variables:
1004 \&.\[rs]" mode: nroff
1010 There is a set of file name extensions, e.g.\& the man pages that
1011 trigger the automatic activation of the
1016 Theoretically, it is possible to write the sequence
1021 \&.\[rs]" \%-*-\ nroff\ -*-
1026 as the first line of a file to have it started in
1030 Unfortunately, some applications such as the
1032 program are confused by this; so this is deprecated.
1037 formatters provide automated line breaks and horizontal and vertical
1040 In order to not disturb this, the following tips can be helpful.
1043 Never include empty or blank lines in a
1047 Instead, use the empty request (a line consisting of a dot only) or a
1050 if a structuring element is needed.
1053 Never start a line with whitespace because this can lead to
1054 unexpected behavior.
1056 Indented paragraphs can be constructed in a controlled way by
1061 Start each sentence on a line of its own, for the spacing after a dot
1062 is handled differently depending on whether it terminates an
1063 abbreviation or a sentence.
1065 To distinguish both cases, do a line break after each sentence.
1068 To additionally use the auto-fill mode in Emacs, it is best to insert
1071 request (a line consisting of a dot only) after each sentence.
1074 The following example shows how optimal
1081 This is an example for a
1085 This is the next sentence in the same paragraph.
1087 This is a longer sentence stretching over several
1088 lines; abbreviations like `cf.' are easily
1089 identified because the dot is not followed by a
1092 In the output, this will still go to the same
1098 Besides Emacs, some other editors provide
1100 style files too, e.g.\&
1107 .\" --------------------------------------------------------------------
1109 .\" --------------------------------------------------------------------
1112 is a registered trademark of the Open Group.
1114 But things have improved considerably after Caldera had bought SCO
1118 .\" --------------------------------------------------------------------
1120 .\" --------------------------------------------------------------------
1122 There is a lot of documentation on
1125 The original papers on classical
1127 are still available, and all aspects of
1129 are documented in great detail.
1132 .\" --------------------------------------------------------------------
1133 .SS "Internet sites"
1134 .\" --------------------------------------------------------------------
1138 .UR http://\:www.troff.org
1139 The historical troff site
1141 provides an overview and pointers to all historical aspects of
1146 .UR http://\:www.multicians.org
1149 contains a lot of information on the MIT projects, CTSS, Multics,
1150 early Unix, including
1152 especially useful are a glossary and the many links to ancient
1157 .UR http://\:www.tuhs.org/\:Archive/
1158 The Ancient Unixes Archive
1161 provides the source code and some binaries of the ancient Unixes
1162 (including the source code of
1164 and its documentation) that were made public by Caldera since 2001,
1165 e.g.\& of the famous Unix version\~7 for PDP-11 at the
1166 .UR http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7 .
1171 Developers at AT&T Bell Labs
1172 .UR http://\:www.bell-labs.com/
1173 Bell Labs Computing and Mathematical Sciences Research
1176 provides a search facility for tracking information on the early
1181 .UR http://\:plan9.bell-labs.com
1182 The Plan\~9 operating system
1189 .UR http://web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
1190 Jerry Saltzer's home page
1193 stores some documents using the ancient RUNOFF formatting language.
1197 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html
1198 The Bell Labs CSTR site
1203 manuals (CSTR #54, #97, #114, #116, #122) and famous historical
1204 documents on programming.
1207 \f[CR]GNU\f[] \f[I]roff\f[]
1208 .UR http://\:www.gnu.org/\:software/\:groff
1219 .\" --------------------------------------------------------------------
1220 .SS "Historical roff Documentation"
1221 .\" --------------------------------------------------------------------
1225 documents are still available on-line.
1227 The two main manuals of the
1234 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz ;
1235 .I "Nroff/\:Troff User's Manual"
1238 Bell Labs, 1976; revised by Brian Kernighan, 1992.
1243 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz ,
1244 .I "A Typesetter-independent TROFF"
1247 Bell Labs, 1981, revised March 1982.
1250 The \[lq]little language\[rq]
1256 Jon L. Bentley and Brian W. Kernighan,
1257 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:114.ps.gz ;
1258 .I "GRAP \[en] A Language for Typesetting Graphs"
1261 Bell Labs, August 1984.
1266 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz ;
1267 .I "PIC \[en] A Graphics Language for Typesetting"
1270 Bell Labs, December 1984.
1274 J. L. Bentley, L. W. Jelinski, and B. W. Kernighan,
1275 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz ;
1276 .I "CHEM \[en] A Program for Typesetting Chemical Structure Diagrams,"
1277 .I "Computers and Chemistry"
1280 Bell Labs, April 1986.
1283 .\" --------------------------------------------------------------------
1285 .\" --------------------------------------------------------------------
1287 Due to its complex structure, a full
1289 system has many man pages, each describing a single aspect of
1292 Unfortunately, there is no general naming scheme for the documentation
1301 .BR groff (@MAN1EXT@)
1302 contains a survey of all documentation available in
1306 On other systems, you are on your own, but
1308 might be a good starting point.
1311 .\" --------------------------------------------------------------------
1313 .\" --------------------------------------------------------------------
1315 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007
1316 Free Software Foundation, Inc.
1319 This document is distributed under the terms of the \f[CR]FDL\f[]
1320 (\f[CR]GNU Free Documentation License\f[]) version 1.1 or later.
1322 You should have received a copy of the \f[CR]FDL\f[] on your system,
1323 it is also available on-line at the
1324 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html .
1329 This document is part of
1336 .MT bwarken@mayn.de ;
1344 .\" --------------------------------------------------------------------
1346 .\" --------------------------------------------------------------------
1348 .\" Local Variables: