5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007, 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 A copy of the Free Documentation License is included as a file called
19 FDL in the main directory of the groff source package.
23 .\" --------------------------------------------------------------------
29 . nop \f[B]\[rs]\\*[@1]\f[]\\$*
37 . nop `\f[B]\\*[@1]\f[]'\\$*
42 .\" --------------------------------------------------------------------
44 .\" --------------------------------------------------------------------
46 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
48 roff \- concepts and history of roff typesetting
51 .\" --------------------------------------------------------------------
53 .\" --------------------------------------------------------------------
56 is the general name for a set of type-setting programs, known under
66 type-setting system consists of an extensible text formatting language
67 and a set of programs for printing and converting to other text
70 Traditionally, it is the main text processing system of Unix; every
71 Unix-like operating system still distributes a
73 system as a core package.
78 system today is the free software implementation \f[CR]GNU\f[]
80 .BR groff (@MAN1EXT@).
84 implementations are referred to as
86 (dating back as long as 1973).
89 implements the look-and-feel and functionality of its classical
90 ancestors, but has many extensions.
93 In some ancient Unix systems, there was a binary called
95 that implemented the even more ancient
99 operating system, cf.\& section
101 The functionality of this program was very restricted even in
102 comparison to ancient
104 it is not supported any longer.
106 Consequently, in this document, the term
108 always refers to the general meaning of
117 is in wide use today, for example, the manual pages on UNIX systems
118 .RI ( man\~pages\/ ),
119 many software books, system documentation, standards, and corporate
120 documents are written in roff.
124 output for text devices is still unmatched, and its graphical output
125 has the same quality as other free type-setting programs and is better
126 than some of the commercial systems.
129 The most popular application of
135 this is the standard documentation system on many operating systems.
138 This document describes the historical facts around the development
141 some usage aspects common to all
143 versions, details on the
145 pipeline, which is usually hidden behind front-ends like
146 .BR groff (@MAN1EXT@);
147 a general overview of the formatting language; some tips for editing
149 files; and many pointers to further readings.
152 .\" --------------------------------------------------------------------
154 .\" --------------------------------------------------------------------
158 text processing system has a very long history, dating back to the
163 system itself is intimately connected to the Unix operating system,
164 but its roots go back to the earlier operating systems CTSS and
168 .\" --------------------------------------------------------------------
169 .SS "The Predecessor RUNOFF"
170 .\" --------------------------------------------------------------------
175 is intimately related to the history of the operating systems.
184 .RI ( "Compatible Time Sharing System" )
185 as early as 1964 \[en] note that CTSS commands were all uppercase.
187 When CTSS was further developed into the operating system
188 .UR http://\:www.multicians.org
191 the famous predecessor of Unix from 1963,
193 has been improved further by people from the Massachusetts Institute of
194 Technology (MIT) and the Bell Technical Laboratory (BTL), including Dennis
195 Ritchie and Joe Ossanna.
197 .BR "Multics runoff" ,
198 for example, was now able to do two-pass operations; it became the main
199 format for documentation and text processing.
201 Both operating systems could only be run on very expensive computers
202 at that time, so they were mostly used in research and for official
206 The possibilities of the
208 language were quite limited as compared to modern
211 Only text output was possible in the 1960s.
213 This could be implemented by a set of requests of length\~2, many of
214 which are still identically used in
217 The language was modelled according to the habits of typesetting in
218 the pre-computer age, where lines starting with a dot were used in
219 manuscripts to denote formatting requests to the person who would
220 perform the typesetting manually later on.
223 The runoff program was written in the
225 language first, later on in
227 the grandmother of the
229 programming language.
231 In the Multics operating system, the help system was handled by
234 task to manage the Unix manual pages.
236 On the other hand, BCPL and runoff were ported to the GCOS system
237 at Bell Labs since BTL left the development of Multics.
240 There are still documents written in the RUNOFF language; for examples
241 see Saltzer's home page, cf.\& section
245 .\" --------------------------------------------------------------------
246 .SS "The Classical nroff/troff System"
247 .\" --------------------------------------------------------------------
249 At the Bell Labs, there was a need to
251 .I Graphic Systems CAT
252 typesetter, a graphical output device from a PDP-11 computer running
255 As runoff was too limited for this task it was further developed into
256 a more powerful text formatting system by
257 .IR "Josef F. Ossanna" ,
258 who already programmed several runoff ports.
265 The greatly enlarged language of Ossanna's concept included already all
271 systems try to implement compatibility to this system.
273 So Joe Ossanna can be called the father of all
280 had three formatter programs.
284 .RI ( "typesetter roff\/" )
285 generated a graphical output for the
287 typesetter as its only device.
291 produced text output suitable for terminals and line printers.
295 was the reimplementation of the former
297 program with its limited features; this program was abandoned in later
302 is used to refer to a
307 Ossanna's first version was written in the PDP-11 assembly language and
313 development by rewriting it in the C\~programming language.
315 The C\~version was released in 1975.
318 The syntax of the formatting language of the
320 programs was documented in the famous
321 .IR "Troff User's Manual [CSTR\~#54]" ,
322 first published in 1976, with further revisions up to 1992 by Brian
325 This document is the specification of the
326 .IR "classical troff" .
329 systems tried to establish compatibility with this specification.
332 After Ossanna had died in 1977 by a heart-attack at the age of about\~50,
333 Kernighan went on with developing
336 The next milestone was to equip
338 with a general interface to support more devices, the intermediate
339 output format and the postprocessor system.
341 This completed the structure of a
343 as it is still in use today; see section
346 In 1979, these novelties were described in the paper
350 version is the basis for all existing newer
355 On some systems, this
356 .I device independent troff
357 got a binary of its own, called
358 .BR ditroff (@MAN7EXT@).
362 programs already provide the full
364 capabilities automatically.
367 .\" --------------------------------------------------------------------
368 .SS "Commercialization"
369 .\" --------------------------------------------------------------------
371 A major degradation occurred when the easily available Unix\~7
372 operating system was commercialized.
374 A whole bunch of divergent operating systems emerged, fighting each
375 other with incompatibilities in their extensions.
377 Luckily, the incompatibilities did not fight the original
380 All of the different commercial
382 systems made heavy use of Ossanna/\:Kernighan's open source code and
383 documentation, but sold them as \[lq]their\[rq] system \[en] with only
387 The source code of both the ancient Unix and classical
389 weren't available for two decades.
391 Fortunately, Caldera bought SCO UNIX in 2001.
393 In the following, Caldera made the ancient source code accessible
394 on-line for non-commercial use, cf. section
398 .\" --------------------------------------------------------------------
400 .\" --------------------------------------------------------------------
402 The most important free
404 project was the \f[CR]GNU\f[] implementation of
406 written from scratch by James Clark and put under the
407 .UR http://\:www.gnu.org/\:copyleft
416 .BR groff (@MAN1EXT@)
422 system is still actively developed.
424 It is compatible to the classical
426 but many extensions were added.
430 system that is available on almost all operating systems \[en] and it
440 An alternative is Gunnar Ritter's
441 .UR http://\:heirloom.sf.net
442 Heirloom Documentation Tools
444 project, started in 2005, which provides enhanced versions of the various
445 roff tools found in the OpenSolaris and Plan\~9 operating systems, now
446 available under free licenses.
449 .\" --------------------------------------------------------------------
451 .\" --------------------------------------------------------------------
453 Most people won'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't difficult either.
473 implementations provide wrapper programs that make it easy to use the
475 system on the shell command line.
477 For example, the \f[CR]GNU\f[]
480 .BR groff (@MAN1EXT@)
481 provides command line options to avoid the long command pipes of
486 tries to guess from the document which arguments should be used for a
489 people who do not like specifying command line options should try the
490 .BR groffer (@MAN1EXT@)
491 program for graphically displaying
496 .\" --------------------------------------------------------------------
498 .\" --------------------------------------------------------------------
502 system consists of preprocessors,
504 formatter programs, and a set of device postprocessors.
506 This concept makes heavy use of the
508 mechanism, that is, a series of programs is called one after the other,
509 where the output of each program in the queue is taken as the input
510 for the next program.
516 | \f[I]preproc\f[P] \
518 | troff \f[I]options\f[P] \
523 The preprocessors generate
525 code that is fed into a
529 which in turn generates
530 .I intermediate output
531 that is fed into a device postprocessor program for printing or final
535 All of these parts use programming languages of their own; each
536 language is totally unrelated to the other parts.
540 macro packages that were tailored for special purposes can be
546 documents use the macros of some package, intermixed with code for one
547 or more preprocessors, spiced with some elements from the plain
551 The full power of the
553 formatting language is seldom needed by users; only programmers of
554 macro packages need to know about the gory details.
558 .\" --------------------------------------------------------------------
560 .\" --------------------------------------------------------------------
564 preprocessor is any program that generates output that syntactically
565 obeys the rules of the
569 Each preprocessor defines a language of its own that is translated
572 code when run through the preprocessor program.
574 Parts written in these languages may be included within a
576 document; they are identified by special
580 Each document that is enhanced by preprocessor code must be run
581 through all corresponding preprocessors before it is fed into the
584 formatter program, for the formatter just ignores all alien code.
586 The preprocessor programs extract and transform only the document
587 parts that are determined for them.
590 There are a lot of free and commercial
594 Some of them aren't available on each system, but there is a small
595 set of preprocessors that are considered as an integral part of each
599 The classical preprocessors are
606 eqn@for mathematical formul\[ae].
607 pic@for drawing diagrams.
608 refer@for bibliographic references.
609 soelim@for including macro files from standard locations.
610 chem@for drawing chemical formul\[ae].
615 Other known preprocessors that are not available on all systems
622 grap@for constructing graphical elements.
623 grn@for including \fBgremlin\fR(1) pictures.
627 .\" --------------------------------------------------------------------
628 .SS "Formatter Programs"
629 .\" --------------------------------------------------------------------
633 is a program that parses documents written in the
635 formatting language or uses some of the
640 .IR "intermediate output" ,
641 which is intended to be fed into a single device postprocessor that
642 must be specified by a command-line option to the formatter program.
644 The documents must have been run through all necessary preprocessors
648 The output produced by a
650 formatter is represented in yet another language, the
651 .IR "intermediate output format"
654 This language was first specified in
656 its \f[CR]GNU\f[] extension is documented in
657 .BR groff_out (@MAN5EXT@).
659 The intermediate output language is a kind of assembly language
660 compared to the high-level
664 The generated intermediate output is optimized for a special device,
665 but the language is the same for every device.
670 formatter is the heart of the
680 for graphical devices.
685 is used as a general term to refer to both formatters.
688 .\" --------------------------------------------------------------------
689 .SS "Devices and Postprocessors"
690 .\" --------------------------------------------------------------------
692 Devices are hardware interfaces like printers, text or graphical
693 terminals, etc., or software interfaces such as a conversion into a
694 different text or graphical format.
699 postprocessor is a program that transforms
701 output into a form suitable for a special device.
705 postprocessors are like device drivers for the output target.
708 For each device there is a postprocessor program that fits the device
711 The postprocessor parses the generated intermediate output and
712 generates device-specific code that is sent directly to the device.
715 The names of the devices and the postprocessor programs are not fixed
716 because they greatly depend on the software and hardware abilities of
719 For example, the classical devices mentioned in
721 have greatly changed since the classical times.
723 The old hardware doesn't exist any longer and the old graphical
724 conversions were quite imprecise when compared to their modern
728 For example, the Postscript device
732 had a resolution of 720, while
735 device has 72000, a refinement of factor 100.
738 Today the operating systems provide device drivers for most
739 printer-like hardware, so it isn't necessary to write a special
740 hardware postprocessor for each printer.
743 .\" --------------------------------------------------------------------
744 .SH "ROFF PROGRAMMING"
745 .\" --------------------------------------------------------------------
749 are normal text files decorated by
755 formatting language is quite powerful; it is almost a full programming
756 language and provides elements to enlarge the language.
758 With these, it became possible to develop macro packages that are
759 tailored for special applications.
761 Such macro packages are much handier than plain
764 So most people will choose a macro package without worrying about the
770 .\" --------------------------------------------------------------------
772 .\" --------------------------------------------------------------------
774 Macro packages are collections of macros that are suitable to format a
775 special kind of documents in a convenient way.
777 This greatly eases the usage of
780 The macro definitions of a package are kept in a file called
786 All tmac files are stored in one or more directories at standardized
789 Details on the naming of macro packages and their placement is found
791 .BR groff_tmac (@MAN5EXT@).
794 A macro package that is to be used in a document can be announced to
795 the formatter by the command line option
798 .BR troff (@MAN1EXT@),
799 or it can be specified within a document using the file inclusion
803 .BR groff (@MAN7EXT@).
806 Famous classical macro packages are
808 for traditional man pages,
810 for \f[CR]BSD\f[]-style manual pages;
811 the macro sets for books, articles, and letters are
813 (probably from the first name of its creator
818 .IR "Manuscript Macros\/" ),
822 .IR "Memorandum Macros\/" ).
825 .\" --------------------------------------------------------------------
826 .SS "The roff Formatting Language"
827 .\" --------------------------------------------------------------------
831 formatting language is documented in the
832 .I Troff User's Manual
837 language is a full programming language providing requests, definition
838 of macros, escape sequences, string variables, number or size
839 registers, and flow controls.
843 are the predefined basic formatting commands similar to the commands
846 The user can define request-like elements using predefined
850 These are then called
853 A document writer will not note any difference in usage for requests
854 or macros; both are written on a line on their own starting with a dot.
860 elements starting with a backslash
862 They can be inserted anywhere, also in the midst of text in a line.
864 They are used to implement various features, including the insertion of
865 non-\f[CR]ASCII\f[] characters with
869 in-line comments with
871 the escaping of special control characters like
873 and many other features.
877 are variables that can store a string.
879 A string is stored by the
883 The stored string can be retrieved later by the
889 store numbers and sizes.
891 A register can be set with the request
893 and its value can be retrieved by the escape sequence
897 .\" --------------------------------------------------------------------
898 .SH "FILE NAME EXTENSIONS"
899 .\" --------------------------------------------------------------------
901 Manual pages (man pages) take the section number as a file name
902 extension, e.g., the filename for this document is
904 i.e., it is kept in section\~7
908 The classical macro packages take the package name as an extension, e.g.\&
910 for a document using the
926 But there is no general naming scheme for
932 is seen now and then.
934 Maybe there should be a standardization for the filename extensions of
939 File name extensions can be very handy in conjunction with the
943 It provides the possibility to feed all input into a command-line pipe
944 that is specified in the shell environment variable
946 This process is not well documented, so here an example:
951 LESSOPEN='|lesspipe %s'
958 is either a system supplied command or a shell script of your own.
961 .\" --------------------------------------------------------------------
963 .\" --------------------------------------------------------------------
965 The best program for editing a
967 document is Emacs (or Xemacs), see
971 mode that is suitable for all kinds of
975 This mode can be activated by the following methods.
978 When editing a file within Emacs the mode can be changed by typing
979 .RI ` "M-x nroff-mode" ',
982 means to hold down the
991 But it is also possible to have the mode automatically selected when
992 the file is loaded into the editor.
995 The most general method is to include the following 3 comment lines at
1001 \&.\[rs]" Local Variables:
1002 \&.\[rs]" mode: nroff
1008 There is a set of file name extensions, e.g.\& the man pages that
1009 trigger the automatic activation of the
1014 Theoretically, it is possible to write the sequence
1019 \&.\[rs]" \%-*-\ nroff\ -*-
1024 as the first line of a file to have it started in
1028 Unfortunately, some applications such as the
1030 program are confused by this; so this is deprecated.
1035 formatters provide automated line breaks and horizontal and vertical
1038 In order to not disturb this, the following tips can be helpful.
1041 Never include empty or blank lines in a
1045 Instead, use the empty request (a line consisting of a dot only) or a
1048 if a structuring element is needed.
1051 Never start a line with whitespace because this can lead to
1052 unexpected behavior.
1054 Indented paragraphs can be constructed in a controlled way by
1059 Start each sentence on a line of its own, for the spacing after a dot
1060 is handled differently depending on whether it terminates an
1061 abbreviation or a sentence.
1063 To distinguish both cases, do a line break after each sentence.
1066 To additionally use the auto-fill mode in Emacs, it is best to insert
1069 request (a line consisting of a dot only) after each sentence.
1072 The following example shows how optimal
1079 This is an example for a
1083 This is the next sentence in the same paragraph.
1085 This is a longer sentence stretching over several
1086 lines; abbreviations like `cf.' are easily
1087 identified because the dot is not followed by a
1090 In the output, this will still go to the same
1096 Besides Emacs, some other editors provide
1098 style files too, e.g.\&
1105 .\" --------------------------------------------------------------------
1107 .\" --------------------------------------------------------------------
1110 is a registered trademark of the Open Group.
1112 But things have improved considerably after Caldera had bought SCO
1116 .\" --------------------------------------------------------------------
1118 .\" --------------------------------------------------------------------
1120 There is a lot of documentation on
1123 The original papers on classical
1125 are still available, and all aspects of
1127 are documented in great detail.
1130 .\" --------------------------------------------------------------------
1131 .SS "Internet sites"
1132 .\" --------------------------------------------------------------------
1136 .UR http://\:www.troff.org
1137 The historical troff site
1139 provides an overview and pointers to all historical aspects of
1144 .UR http://\:www.multicians.org
1147 contains a lot of information on the MIT projects, CTSS, Multics,
1148 early Unix, including
1150 especially useful are a glossary and the many links to ancient
1155 .UR http://\:www.tuhs.org/\:Archive/
1156 The Ancient Unixes Archive
1159 provides the source code and some binaries of the ancient Unixes
1160 (including the source code of
1162 and its documentation) that were made public by Caldera since 2001,
1163 e.g.\& of the famous Unix version\~7 for PDP-11 at the
1164 .UR http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7
1169 Developers at AT&T Bell Labs
1170 .UR http://\:www.bell-labs.com/
1171 Bell Labs Computing and Mathematical Sciences Research
1174 provides a search facility for tracking information on the early
1179 .UR http://\:plan9.bell-labs.com
1180 The Plan\~9 operating system
1187 .UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
1188 Jerry Saltzer's home page
1191 stores some documents using the ancient RUNOFF formatting language.
1195 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html
1196 The Bell Labs CSTR site
1201 manuals (CSTR #54, #97, #114, #116, #122) and famous historical
1202 documents on programming.
1205 \f[CR]GNU\f[] \f[I]roff\f[]
1206 .UR http://\:www.gnu.org/\:software/\:groff
1217 .\" --------------------------------------------------------------------
1218 .SS "Historical roff Documentation"
1219 .\" --------------------------------------------------------------------
1223 documents are still available on-line.
1225 The two main manuals of the
1232 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
1233 .I "Nroff/\:Troff User's Manual"
1236 Bell Labs, 1976; revised by Brian Kernighan, 1992.
1241 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz
1242 .I "A Typesetter-independent TROFF"
1245 Bell Labs, 1981, revised March 1982.
1248 The \[lq]little language\[rq]
1254 Jon L. Bentley and Brian W. Kernighan,
1255 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:114.ps.gz
1256 .I "GRAP \[en] A Language for Typesetting Graphs"
1259 Bell Labs, August 1984.
1264 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz
1265 .I "PIC \[en] A Graphics Language for Typesetting"
1268 Bell Labs, December 1984.
1272 J. L. Bentley, L. W. Jelinski, and B. W. Kernighan,
1273 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
1274 .I "CHEM \[en] A Program for Typesetting Chemical Structure Diagrams,"
1275 .I "Computers and Chemistry"
1278 Bell Labs, April 1986.
1281 .\" --------------------------------------------------------------------
1283 .\" --------------------------------------------------------------------
1285 Due to its complex structure, a full
1287 system has many man pages, each describing a single aspect of
1290 Unfortunately, there is no general naming scheme for the documentation
1299 .BR groff (@MAN1EXT@)
1300 contains a survey of all documentation available in
1304 On other systems, you are on your own, but
1306 might be a good starting point.
1309 .\" --------------------------------------------------------------------
1311 .\" --------------------------------------------------------------------
1313 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007
1314 Free Software Foundation, Inc.
1317 This document is distributed under the terms of the \f[CR]FDL\f[]
1318 (\f[CR]GNU Free Documentation License\f[]) version 1.1 or later.
1320 You should have received a copy of the \f[CR]FDL\f[] on your system,
1321 it is also available on-line at the
1322 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1327 This document is part of
1342 .\" --------------------------------------------------------------------
1344 .\" --------------------------------------------------------------------
1346 .\" Local Variables: