5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009
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.3 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 text formatting programs, known under
66 system consists of an extensible text formatting language and a set of
67 programs for printing and converting to other text formats.
69 Unix-like operating systems distribute a
71 system as a core package.
76 system today is the free software implementation \f[CR]GNU\f[]
78 .BR groff (@MAN1EXT@).
81 implements the look-and-feel and functionality of its ancestors, with many
87 is described in section
90 In this document, the term
92 always refers to the general class of roff programs, not to the
94 command provided in early UNIX systems.
99 is in wide use today, for example, the manual pages on UNIX systems
100 .RI ( man\~pages\/ ),
101 many software books, system documentation, standards, and corporate
102 documents are written in roff.
106 output for text devices is still unmatched, and its graphical output
107 has the same quality as other free type-setting programs and is better
108 than some of the commercial systems.
112 is used to format UNIX
116 the standard documentation system on many UNIX-derived operating systems.
119 This document describes the history of the development of the
121 some usage aspects common to all
123 versions, details on the
125 pipeline, which is usually hidden behind front-ends like
126 .BR groff (@MAN1EXT@);
127 a general overview of the formatting language; some tips for editing
129 files; and many pointers to further readings.
132 .\" --------------------------------------------------------------------
134 .\" --------------------------------------------------------------------
136 Document formatting by computer dates back to the 1960s.
140 system itself is intimately connected to the Unix operating system, but its
141 roots go back to the earlier operating systems CTSS and Multics.
144 .\" --------------------------------------------------------------------
145 .SS "The Predecessor RUNOFF"
146 .\" --------------------------------------------------------------------
151 was written in the MAD language by
154 .IR "Compatible Time Sharing System (CTSS)" ,
155 a project of the Massachusetts Institute of Technology (MIT), in 1963 and
156 1964 \[en] note that CTSS commands were all uppercase.
159 In 1965, MIT's Project MAC teamed with Bell Telephone Laboratories (BTL)
160 and General Electric to begin the
161 .UR http://\:www.multicians.org
168 was written for Multics in the late 60s in the BCPL language, by
171 and other members of the Multics team.
174 Like its CTSS ancestor, Multics
176 formatted an input file consisting of text and command lines; commands began
177 with a period and were two letters.
179 Output from these commands was to terminal devices such as IBM Selectric
184 had additional features added, such as the ability to do two-pass
185 formatting; it became the main format for Multics documentation and text
191 were ported to the GCOS system at Bell Labs when BTL left the development of
195 .\" --------------------------------------------------------------------
196 .SS "The Classical nroff/troff System"
197 .\" --------------------------------------------------------------------
199 At BTL, there was a need to drive the
200 .I Graphic Systems CAT
201 typesetter, a graphical output device from a PDP-11 computer running Unix.
205 was too limited for this task it was further developed into a more
206 powerful text formatting system by
207 .IR "Joseph F.\& Ossanna" ,
208 who already programmed several runoff ports.
216 The greatly enlarged language of Ossanna's version already included all
222 systems try to implement compatibility to this system.
224 So Joe Ossanna can be called the father of all
231 had three formatter programs.
235 .RI ( "typesetter roff\/" )
236 generated a graphical output for the
238 typesetter as its only device.
242 produced text output suitable for terminals and line printers.
246 was the reimplementation of the former
248 program with its limited features; this program was abandoned in later
253 is used to refer to a
258 Ossanna's first version was written in the PDP-11 assembly language and
264 development by rewriting it in the C\~programming language.
266 The C\~version was released in 1975.
269 The syntax of the formatting language of the
271 programs was documented in the famous
272 .IR "Troff User's Manual [CSTR\~#54]" ,
273 first published in 1976, with further revisions up to 1992 by Brian
276 This document is the specification of the
277 .IR "classical troff" .
281 systems tried to establish compatibility with this specification.
284 After Ossanna's death in 1977, Kernighan went on with developing
287 In the late 1970s, Kernighan equipped
289 with a general interface to support more devices, the intermediate
290 output format, and the postprocessor system.
292 This completed the structure of a
294 as it is still in use today; see section
297 In 1979, these novelties were described in the paper
302 version is the basis for all existing newer troff systems, including
305 On some systems, this
306 .I device independent troff
307 got a binary of its own, called
308 .BR ditroff (@MAN7EXT@).
312 programs already provide the full
314 capabilities automatically.
317 .\" --------------------------------------------------------------------
319 .\" --------------------------------------------------------------------
321 The source code of both the ancient Unix and classical
323 weren't available for two decades.
325 Meanwhile, it is accessible again (on-line) for non-commercial use,
330 .\" --------------------------------------------------------------------
332 .\" --------------------------------------------------------------------
334 The most important free
336 project was the \f[CR]GNU\f[] implementation of
338 written from scratch by
341 .UR http://\:www.gnu.org/\:copyleft
351 .BR groff (@MAN1EXT@)
357 system is still actively developed.
359 It is compatible to the classical
361 but many extensions were added.
365 system that is available on almost all operating systems \[en] and it is
376 .IR "Gunnar Ritter" 's
377 .UR http://\:heirloom.sf.net
378 Heirloom Documentation Tools
380 project, started in 2005, which provides enhanced versions of the various
381 roff tools found in the OpenSolaris and Plan\~9 operating systems, now
382 available under free licenses.
385 .\" --------------------------------------------------------------------
387 .\" --------------------------------------------------------------------
389 Most people won't even notice that they are actually using
392 When you read a system manual page (man page)
394 is working in the background.
397 documents can be viewed with a native viewer called
399 a standard program of the X window distribution, see
404 explicitly isn't difficult either.
409 implementations provide wrapper programs that make it easy to use the
411 system on the shell command line.
413 For example, the \f[CR]GNU\f[]
416 .BR groff (@MAN1EXT@)
417 provides command line options to avoid the long command pipes of
422 tries to guess from the document which arguments should be used for a
425 people who do not like specifying command line options should try the
426 .BR groffer (@MAN1EXT@)
427 program for graphically displaying
432 .\" --------------------------------------------------------------------
434 .\" --------------------------------------------------------------------
438 system consists of preprocessors,
440 formatter programs, and a set of device postprocessors.
442 This concept makes heavy use of the
444 mechanism, that is, a series of programs is called one after the other,
445 where the output of each program in the queue is taken as the input
446 for the next program.
452 | \f[I]preproc\f[P] \
454 | troff \f[I]options\f[P] \
459 The preprocessors generate
461 code that is fed into a
465 which in turn generates
466 .I intermediate output
467 that is fed into a device postprocessor program for printing or final
471 All of these parts use programming languages of their own; each
472 language is totally unrelated to the other parts.
476 macro packages that were tailored for special purposes can be
482 documents use the macros of some package, intermixed with code for one
483 or more preprocessors, spiced with some elements from the plain
487 The full power of the
489 formatting language is seldom needed by users; only programmers of
490 macro packages need to know about the gory details.
494 .\" --------------------------------------------------------------------
496 .\" --------------------------------------------------------------------
500 preprocessor is any program that generates output that syntactically
501 obeys the rules of the
505 Each preprocessor defines a language of its own that is translated
508 code when run through the preprocessor program.
510 Parts written in these languages may be included within a
512 document; they are identified by special
516 Each document that is enhanced by preprocessor code must be run
517 through all corresponding preprocessors before it is fed into the
520 formatter program, for the formatter just ignores all alien code.
522 The preprocessor programs extract and transform only the document
523 parts that are determined for them.
526 There are a lot of free and commercial
530 Some of them aren't available on each system, but there is a small
531 set of preprocessors that are considered as an integral part of each
535 The classical preprocessors are
542 eqn@for mathematical formul\[ae].
543 pic@for drawing diagrams.
544 refer@for bibliographic references.
545 soelim@for including macro files from standard locations.
546 chem@for drawing chemical formul\[ae].
551 Other known preprocessors that are not available on all systems
558 grap@for constructing graphical elements.
559 grn@for including \fBgremlin\fR(1) pictures.
563 .\" --------------------------------------------------------------------
564 .SS "Formatter Programs"
565 .\" --------------------------------------------------------------------
569 is a program that parses documents written in the
571 formatting language or uses some of the
576 .IR "intermediate output" ,
577 which is intended to be fed into a single device postprocessor that
578 must be specified by a command-line option to the formatter program.
580 The documents must have been run through all necessary preprocessors
584 The output produced by a
586 formatter is represented in yet another language, the
587 .IR "intermediate output format"
591 This language was first specified in
593 its \f[CR]GNU\f[] extension is documented in
594 .BR groff_out (@MAN5EXT@).
596 The intermediate output language is a kind of assembly language
597 compared to the high-level
601 The generated intermediate output is optimized for a special device,
602 but the language is the same for every device.
607 formatter is the heart of the
617 for graphical devices.
622 is used as a general term to refer to both formatters.
625 .\" --------------------------------------------------------------------
626 .SS "Devices and Postprocessors"
627 .\" --------------------------------------------------------------------
629 Devices are hardware interfaces like printers, text or graphical
630 terminals, etc., or software interfaces such as a conversion into a
631 different text or graphical format.
636 postprocessor is a program that transforms
638 output into a form suitable for a special device.
642 postprocessors are like device drivers for the output target.
645 For each device there is a postprocessor program that fits the device
648 The postprocessor parses the generated intermediate output and
649 generates device-specific code that is sent directly to the device.
652 The names of the devices and the postprocessor programs are not fixed
653 because they greatly depend on the software and hardware abilities of
656 For example, the classical devices mentioned in
658 have greatly changed since the classical times.
660 The old hardware doesn't exist any longer and the old graphical
661 conversions were quite imprecise when compared to their modern
665 For example, the Postscript device
669 had a resolution of 720 units per inch, while
672 device has 72000, a refinement of factor 100.
675 Today the operating systems provide device drivers for most
676 printer-like hardware, so it isn't necessary to write a special
677 hardware postprocessor for each printer.
680 .\" --------------------------------------------------------------------
681 .SH "ROFF PROGRAMMING"
682 .\" --------------------------------------------------------------------
686 are normal text files decorated by
692 formatting language is quite powerful; it is almost a full programming
693 language and provides elements to enlarge the language.
695 With these, it became possible to develop macro packages that are
696 tailored for special applications.
698 Such macro packages are much handier than plain
701 So most people will choose a macro package without worrying about the
707 .\" --------------------------------------------------------------------
709 .\" --------------------------------------------------------------------
711 Macro packages are collections of macros that are suitable to format a
712 special kind of documents in a convenient way.
714 This greatly eases the usage of
717 The macro definitions of a package are kept in a file called
723 All tmac files are stored in one or more directories at standardized
726 Details on the naming of macro packages and their placement is found
728 .BR groff_tmac (@MAN5EXT@).
731 A macro package that is to be used in a document can be announced to
732 the formatter by the command line option
735 .BR troff (@MAN1EXT@),
736 or it can be specified within a document using the file inclusion
740 .BR groff (@MAN7EXT@).
743 Famous classical macro packages are
745 for traditional man pages,
747 for \f[CR]BSD\f[]-style manual pages;
748 the macro sets for books, articles, and letters are
750 (probably from the first name of its creator
755 .IR "Manuscript Macros\/" ),
759 .IR "Memorandum Macros\/" ).
762 .\" --------------------------------------------------------------------
763 .SS "The roff Formatting Language"
764 .\" --------------------------------------------------------------------
768 formatting language is documented in the
769 .I Troff User's Manual
774 language is a full programming language providing requests, definition
775 of macros, escape sequences, string variables, number or size
776 registers, and flow controls.
780 are the predefined basic formatting commands similar to the commands
783 The user can define request-like elements using predefined
787 These are then called
790 A document writer will not note any difference in usage for requests
791 or macros; both are written on a line on their own starting with a dot.
797 elements starting with a backslash
800 They can be inserted anywhere, also in the midst of text in a line.
802 They are used to implement various features, including the insertion of
803 non-\f[CR]ASCII\f[] characters with
807 in-line comments with
809 the escaping of special control characters like
811 and many other features.
815 are variables that can store a string.
817 A string is stored by the
821 The stored string can be retrieved later by the
827 store numbers and sizes.
829 A register can be set with the request
831 and its value can be retrieved by the escape sequence
835 .\" --------------------------------------------------------------------
836 .SH "FILE NAME EXTENSIONS"
837 .\" --------------------------------------------------------------------
839 Manual pages (man pages) take the section number as a file name
840 extension, e.g., the filename for this document is
842 i.e., it is kept in section\~7
846 The classical macro packages take the package name as an extension, e.g.\&
848 for a document using the
864 But there is no general naming scheme for
870 is seen now and then.
872 Maybe there should be a standardization for the filename extensions of
877 File name extensions can be very handy in conjunction with the
881 It provides the possibility to feed all input into a command-line pipe
882 that is specified in the shell environment variable
885 This process is not well documented, so here an example:
890 LESSOPEN='|lesspipe %s'
897 is either a system supplied command or a shell script of your own.
900 .\" --------------------------------------------------------------------
902 .\" --------------------------------------------------------------------
904 The best program for editing a
906 document is Emacs (or Xemacs), see
911 mode that is suitable for all kinds of
915 This mode can be activated by the following methods.
918 When editing a file within Emacs the mode can be changed by typing
919 .RI ` "M-x nroff-mode" ',
922 means to hold down the
931 But it is also possible to have the mode automatically selected when
932 the file is loaded into the editor.
935 The most general method is to include the following 3 comment lines at
941 \&.\[rs]" Local Variables:
942 \&.\[rs]" mode: nroff
948 There is a set of file name extensions, e.g.\& the man pages that
949 trigger the automatic activation of the
954 Theoretically, it is possible to write the sequence
959 \&.\[rs]" \%-*-\ nroff\ -*-
964 as the first line of a file to have it started in
968 Unfortunately, some applications such as the
970 program are confused by this; so this is deprecated.
975 formatters provide automated line breaks and horizontal and vertical
978 In order to not disturb this, the following tips can be helpful.
981 Never include empty or blank lines in a
985 Instead, use the empty request (a line consisting of a dot only) or a
988 if a structuring element is needed.
991 Never start a line with whitespace because this can lead to
994 Indented paragraphs can be constructed in a controlled way by
999 Start each sentence on a line of its own, for the spacing after a dot
1000 is handled differently depending on whether it terminates an
1001 abbreviation or a sentence.
1003 To distinguish both cases, do a line break after each sentence.
1006 To additionally use the auto-fill mode in Emacs, it is best to insert
1009 request (a line consisting of a dot only) after each sentence.
1012 The following example shows how optimal
1019 This is an example for a
1023 This is the next sentence in the same paragraph.
1025 This is a longer sentence stretching over several
1026 lines; abbreviations like `cf.' are easily
1027 identified because the dot is not followed by a
1030 In the output, this will still go to the same
1036 Besides Emacs, some other editors provide
1038 style files too, e.g.\&
1045 .\" --------------------------------------------------------------------
1047 .\" --------------------------------------------------------------------
1049 There is a lot of documentation on
1052 The original papers on classical
1054 are still available, and all aspects of
1056 are documented in great detail.
1059 .\" --------------------------------------------------------------------
1060 .SS "Internet sites"
1061 .\" --------------------------------------------------------------------
1065 .UR http://\:www.troff.org
1066 The historical troff site
1068 provides an overview and pointers to all historical aspects of
1073 .UR http://\:www.multicians.org
1076 contains a lot of information on the MIT projects, CTSS, Multics,
1077 early Unix, including
1079 especially useful are a glossary and the many links to ancient
1084 .UR http://\:www.tuhs.org/\:Archive/
1085 The Ancient Unixes Archive
1088 provides the source code and some binaries of the ancient Unixes
1089 (including the source code of
1091 and its documentation) that were made public by Caldera since 2001,
1092 e.g.\& of the famous Unix version\~7 for PDP-11 at the
1093 .UR http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7
1098 Developers at AT&T Bell Labs
1099 .UR http://\:www.bell-labs.com/
1100 Bell Labs Computing and Mathematical Sciences Research
1103 provides a search facility for tracking information on the early
1108 .UR http://\:plan9.bell-labs.com
1109 The Plan\~9 operating system
1116 .UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
1117 Jerry Saltzer's home page
1120 stores some documents using the ancient RUNOFF formatting language.
1124 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html
1125 The Bell Labs CSTR site
1130 manuals (CSTR #54, #97, #114, #116, #122) and famous historical
1131 documents on programming.
1134 \f[CR]GNU\f[] \f[I]roff\f[]
1135 .UR http://\:www.gnu.org/\:software/\:groff
1146 .\" --------------------------------------------------------------------
1147 .SS "Historical roff Documentation"
1148 .\" --------------------------------------------------------------------
1152 documents are still available on-line.
1154 The two main manuals of the
1161 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
1162 .I "Nroff/\:Troff User's Manual"
1165 Bell Labs, 1976; revised by Brian Kernighan, 1992.
1170 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz
1171 .I "A Typesetter-independent TROFF"
1174 Bell Labs, 1981, revised March 1982.
1177 The \[lq]little language\[rq]
1183 Jon L. Bentley and Brian W. Kernighan,
1184 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:114.ps.gz
1185 .I "GRAP \[en] A Language for Typesetting Graphs"
1188 Bell Labs, August 1984.
1193 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz
1194 .I "PIC \[en] A Graphics Language for Typesetting"
1197 Bell Labs, December 1984.
1201 J. L. Bentley, L. W. Jelinski, and B. W. Kernighan,
1202 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
1203 .I "CHEM \[en] A Program for Typesetting Chemical Structure Diagrams,"
1204 .I "Computers and Chemistry"
1207 Bell Labs, April 1986.
1210 .\" --------------------------------------------------------------------
1212 .\" --------------------------------------------------------------------
1214 Due to its complex structure, a full
1216 system has many man pages, each describing a single aspect of
1219 Unfortunately, there is no general naming scheme for the documentation
1228 .BR groff (@MAN1EXT@)
1229 contains a survey of all documentation available in
1233 On other systems, you are on your own, but
1235 might be a good starting point.
1238 .\" --------------------------------------------------------------------
1240 .\" --------------------------------------------------------------------
1242 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009
1243 Free Software Foundation, Inc.
1246 This document is distributed under the terms of the \f[CR]FDL\f[]
1247 (\f[CR]GNU Free Documentation License\f[]) version 1.3 or later.
1249 You should have received a copy of the \f[CR]FDL\f[] on your system,
1250 it is also available on-line at the
1251 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1256 This document is part of
1271 .\" --------------------------------------------------------------------
1273 .\" --------------------------------------------------------------------
1275 .\" Local Variables:
projects / dragonfly.git / blob