1 '\" t -- preprocess: tbl(1)
5 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
7 Copyright (C) 2000 - 2004, 2006 - 2008
8 Free Software Foundation, Inc.
9 written by Bernd Warken <bwarken@mayn.de>
10 maintained by Werner Lemberg <wl@gnu.org>
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.1 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being this .ig-section and AUTHORS, with no
16 Front-Cover Texts, and with no Back-Cover Texts.
18 You should have received a copy of the Free Documentation License
19 as part of the file COPYING; also located in the main directory of the
20 source package of this program.
29 . nop \f[B]\[rs]\\*[@1]\f[]\\$*
37 . nop `\f[B]\\*[@1]\f[]'\\$*
46 .TH @U_ROFF@-HISTORY @MAN7EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
48 @T_ROFF@-history \- concepts and history of roff typesetting
56 is the general name for a set of text formatting programs, known under
65 system consists of an extensible text formatting language and a set of
66 programs for printing and converting to other text formats.
68 Unix-like operating systems distribute a
70 system as a core package.
75 system today is the free software implementation \f[CR]GNU\f[]
77 @T_ROFF@ is an deriviative.
78 Both implement the look-and-feel and functionality of its ancestors, with
84 is described in section
87 In this document, the term
89 always refers to the general class of roff programs, not to the
91 command provided in early UNIX systems.
96 is in wide use today, for example, the manual pages on UNIX systems
98 many software books, system documentation, standards, and corporate
99 documents are written in roff.
103 output for text devices is still unmatched, and its graphical output
104 has the same quality as other free type-setting programs and is better
105 than some of the commercial systems.
109 is used to format UNIX
113 the standard documentation system on many UNIX-derived operating systems.
116 This document describes the history of the development of the
118 some usage aspects common to all
120 versions, details on the
122 pipeline, which is usually hidden behind front-ends like
123 .BR @L_ROFF@ (@MAN1EXT@);
124 a general overview of the formatting language; some tips for editing
126 files; and many pointers to further readings.
133 Document formatting by computer dates back to the 1960s.
137 system itself is intimately connected to the Unix operating system, but its
138 roots go back to the earlier operating systems CTSS and Multics.
142 .SS "The Predecessor RUNOFF"
148 was written in the MAD language by
151 .IR "Compatible Time Sharing System (CTSS)" ,
152 a project of the Massachusetts Institute of Technology (MIT), in 1963 and
153 1964 \[en] note that CTSS commands were all uppercase.
156 In 1965, MIT's Project MAC teamed with Bell Telephone Laboratories (BTL)
157 and General Electric to begin the
158 .UR http://\:www.multicians.org
165 was written for Multics in the late 60s in the BCPL language, by
168 and other members of the Multics team.
171 Like its CTSS ancestor, Multics
173 formatted an input file consisting of text and command lines; commands began
174 with a period and were two letters.
176 Output from these commands was to terminal devices such as IBM Selectric
181 had additional features added, such as the ability to do two-pass
182 formatting; it became the main format for Multics documentation and text
188 were ported to the GCOS system at Bell Labs when BTL left the development of
193 .SS "The Classical nroff/troff System"
196 At BTL, there was a need to drive the
197 .I Graphic Systems CAT
198 typesetter, a graphical output device from a PDP-11 computer running Unix.
202 was too limited for this task it was further developed into a more
203 powerful text formatting system by
204 .IR "Joseph F.\& Ossanna" ,
205 who already programmed several runoff ports.
213 The greatly enlarged language of Ossanna's version already included all
219 systems try to implement compatibility to this system.
221 So Joe Ossanna can be called the father of all
228 had three formatter programs.
232 .RI ( "typesetter roff\/" )
233 generated a graphical output for the
235 typesetter as its only device.
239 produced text output suitable for terminals and line printers.
243 was the reimplementation of the former
245 program with its limited features; this program was abandoned in later
250 is used to refer to a
255 Ossanna's first version was written in the PDP-11 assembly language and
261 development by rewriting it in the C\~programming language.
263 The C\~version was released in 1975.
266 The syntax of the formatting language of the
268 programs was documented in the famous
269 .IR "Troff User's Manual [CSTR\~#54]" ,
270 first published in 1976, with further revisions up to 1992 by Brian
273 This document is the specification of the
274 .IR "classical troff" .
278 systems tried to establish compatibility with this specification.
281 After Ossanna's death in 1977, Kernighan went on with developing
284 In the late 1970s, Kernighan equipped
286 with a general interface to support more devices, the intermediate
287 output format, and the postprocessor system.
289 This completed the structure of a
291 as it is still in use today; see section
294 In 1979, these novelties were described in the paper
299 version is the basis for all existing newer troff systems, including
302 On some systems, this
303 .I device independent troff
304 got a binary of its own, called
305 .BR ditroff (@MAN7EXT@).
309 programs already provide the full
311 capabilities automatically.
318 The source code of both the ancient Unix and classical
320 weren't available for two decades.
322 Meanwhile, it is accessible again (on-line) for non-commercial use,
331 The most important free
333 project was the \f[CR]GNU\f[] implementation of
335 written from scratch by
338 .UR http://\:www.gnu.org/\:copyleft
347 Further forks exists.
349 .BR @L_ROFF@ (@MAN1EXT@)
352 It is compatible to the classical
354 but many extensions were added.
358 system that is available on almost all operating systems \[en] and it is
362 An alternative is the
363 .UR https://\:github.com/\:n-t-roff/\:heirloom-doctools
365 project, started in 2005, which provides enhanced versions of the various
366 roff tools found in the OpenSolaris and Plan\~9 operating systems, now
367 available under free licenses.
374 Most people won't even notice that they are actually using
377 When you read a system manual page (man page)
379 is working in the background.
384 implementations provide wrapper programs that make it easy to use the
386 system on the shell command line.
388 For example, the \f[CR]GNU\f[]
391 .BR groff (@MAN1EXT@)
392 provides command line options to avoid the long command pipes of
403 system consists of preprocessors,
405 formatter programs, and a set of device postprocessors.
407 This concept makes heavy use of the
409 mechanism, that is, a series of programs is called one after the other,
410 where the output of each program in the queue is taken as the input
411 for the next program.
417 | \f[I]preproc\f[P] \
419 | troff \f[I]options\f[P] \
424 The preprocessors generate
426 code that is fed into a
430 which in turn generates
431 .I intermediate output
432 that is fed into a device postprocessor program for printing or final
436 All of these parts use programming languages of their own; each
437 language is totally unrelated to the other parts.
441 macro packages that were tailored for special purposes can be
447 documents use the macros of some package, intermixed with code for one
448 or more preprocessors, spiced with some elements from the plain
452 The full power of the
454 formatting language is seldom needed by users; only programmers of
455 macro packages need to know about the gory details.
465 preprocessor is any program that generates output that syntactically
466 obeys the rules of the
470 Each preprocessor defines a language of its own that is translated
473 code when run through the preprocessor program.
475 Parts written in these languages may be included within a
477 document; they are identified by special
481 Each document that is enhanced by preprocessor code must be run
482 through all corresponding preprocessors before it is fed into the
485 formatter program, for the formatter just ignores all alien code.
487 The preprocessor programs extract and transform only the document
488 parts that are determined for them.
491 There are a lot of free and commercial
495 Some of them aren't available on each system, but there is a small
496 set of preprocessors that are considered as an integral part of each
500 The classical preprocessors are
507 eqn@for mathematical formul\[ae].
508 pic@for drawing diagrams.
509 refer@for bibliographic references.
510 soelim@for including macro files from standard locations.
511 chem@for drawing chemical formul\[ae].
516 Other known preprocessors that are not available on all systems
523 grap@for constructing graphical elements.
524 grn@for including \fBgremlin\fR(1) pictures.
529 .SS "Formatter Programs"
534 is a program that parses documents written in the
536 formatting language or uses some of the
541 .IR "intermediate output" ,
542 which is intended to be fed into a single device postprocessor that
543 must be specified by a command-line option to the formatter program.
545 The documents must have been run through all necessary preprocessors
549 The output produced by a
551 formatter is represented in yet another language, the
552 .IR "intermediate output format"
556 This language was first specified in
558 its @T_ROFF@ extension is documented in
559 .BR @L_ROFF@-out (@MAN5EXT@).
561 The intermediate output language is a kind of assembly language
562 compared to the high-level
566 The generated intermediate output is optimized for a special device,
567 but the language is the same for every device.
572 formatter is the heart of the
582 for graphical devices.
587 is used as a general term to refer to both formatters.
591 .SS "Devices and Postprocessors"
594 Devices are hardware interfaces like printers, text or graphical
595 terminals, etc., or software interfaces such as a conversion into a
596 different text or graphical format.
601 postprocessor is a program that transforms
603 output into a form suitable for a special device.
607 postprocessors are like device drivers for the output target.
610 For each device there is a postprocessor program that fits the device
613 The postprocessor parses the generated intermediate output and
614 generates device-specific code that is sent directly to the device.
617 The names of the devices and the postprocessor programs are not fixed
618 because they greatly depend on the software and hardware abilities of
621 For example, the classical devices mentioned in
623 have greatly changed since the classical times.
625 The old hardware doesn't exist any longer and the old graphical
626 conversions were quite imprecise when compared to their modern
630 For example, the Postscript device
634 had a resolution of 720 units per inch, while
637 device has 72000, a refinement of factor 100.
640 Today the operating systems provide device drivers for most
641 printer-like hardware, so it isn't necessary to write a special
642 hardware postprocessor for each printer.
646 .SH "ROFF PROGRAMMING"
651 are normal text files decorated by
657 formatting language is quite powerful; it is almost a full programming
658 language and provides elements to enlarge the language.
660 With these, it became possible to develop macro packages that are
661 tailored for special applications.
663 Such macro packages are much handier than plain
666 So most people will choose a macro package without worrying about the
676 Macro packages are collections of macros that are suitable to format a
677 special kind of documents in a convenient way.
679 This greatly eases the usage of
682 The macro definitions of a package are kept in a file called
688 All tmac files are stored in one or more directories at standardized
691 Details on the naming of macro packages and their placement is found
693 .BR @L_ROFF@-tmac (@MAN5EXT@).
696 A macro package that is to be used in a document can be announced to
697 the formatter by the command line option
700 .BR @L_TROFF@ (@MAN1EXT@),
701 or it can be specified within a document using the file inclusion
705 .BR @L_ROFF@ (@MAN7EXT@).
708 Famous classical macro packages are
710 for traditional man pages,
712 for \f[CR]BSD\f[]-style manual pages;
713 the macro sets for books, articles, and letters are
715 (probably from the first name of its creator
720 .IR "Manuscript Macros\/" ),
724 .IR "Memorandum Macros\/" ).
728 .SS "The roff Formatting Language"
733 formatting language is documented in the
734 .I Troff User's Manual
739 language is a full programming language providing requests, definition
740 of macros, escape sequences, string variables, number or size
741 registers, and flow controls.
745 are the predefined basic formatting commands similar to the commands
748 The user can define request-like elements using predefined
752 These are then called
755 A document writer will not note any difference in usage for requests
756 or macros; both are written on a line on their own starting with a dot.
762 elements starting with a backslash
765 They can be inserted anywhere, also in the midst of text in a line.
767 They are used to implement various features, including the insertion of
768 non-\f[CR]ASCII\f[] characters with
772 in-line comments with
774 the escaping of special control characters like
776 and many other features.
780 are variables that can store a string.
782 A string is stored by the
786 The stored string can be retrieved later by the
792 store numbers and sizes.
794 A register can be set with the request
796 and its value can be retrieved by the escape sequence
801 .SH "FILE NAME EXTENSIONS"
804 Manual pages (man pages) take the section number as a file name
805 extension, e.g., the filename for this document is
807 i.e., it is kept in section\~7
811 The classical macro packages take the package name as an extension, e.g.\&
813 for a document using the
829 But there is no general naming scheme for
835 is seen now and then.
837 Maybe there should be a standardization for the filename extensions of
842 File name extensions can be very handy in conjunction with the
846 It provides the possibility to feed all input into a command-line pipe
847 that is specified in the shell environment variable
850 This process is not well documented, so here an example:
855 LESSOPEN='|lesspipe %s'
862 is either a system supplied command or a shell script of your own.
867 There is a lot of documentation on
870 The original papers on classical
872 are still available, and all aspects of
874 are documented in great detail.
883 .UR http://\:www.troff.org
884 The historical troff site
886 provides an overview and pointers to all historical aspects of
891 .UR http://\:www.multicians.org
894 contains a lot of information on the MIT projects, CTSS, Multics,
895 early Unix, including
897 especially useful are a glossary and the many links to ancient
902 .UR http://\:www.tuhs.org/\:Archive/
903 The Ancient Unixes Archive
906 provides the source code and some binaries of the ancient Unixes
907 (including the source code of
909 and its documentation) that were made public by Caldera since 2001,
910 e.g.\& of the famous Unix version\~7 for PDP-11 at the
911 .UR http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7
916 Developers at AT&T Bell Labs
917 .UR http://\:www.bell-labs.com/
918 Bell Labs Computing and Mathematical Sciences Research
921 provides a search facility for tracking information on the early
926 .UR http://\:plan9.bell-labs.com
927 The Plan\~9 operating system
934 .UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
935 Jerry Saltzer's home page
938 stores some documents using the ancient RUNOFF formatting language.
942 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html
943 The Bell Labs CSTR site
948 manuals (CSTR #54, #97, #114, #116, #122) and famous historical
949 documents on programming.
952 \f[CR]GNU\f[] \f[I]roff\f[]
953 .UR http://\:www.gnu.org/\:software/\:groff
954 The GNU troff web site
963 .SS "Historical roff Documentation"
968 documents are still available on-line.
970 The two main manuals of the
977 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
978 .I "Nroff/\:Troff User's Manual"
981 Bell Labs, 1976; revised by Brian Kernighan, 1992.
985 Brian W.\& Kernighan,
986 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz
987 .I "A Typesetter-independent TROFF"
990 Bell Labs, 1981, revised March 1982.
993 The \[lq]little language\[rq]
999 J\. L.\& Bentley and Brian W.\& Kernighan,
1000 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:114.ps.gz
1001 .I "GRAP \[en] A Language for Typesetting Graphs"
1004 Bell Labs, August 1984.
1008 Brian W.\& Kernighan,
1009 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz
1010 .I "PIC \[en] A Graphics Language for Typesetting"
1013 Bell Labs, December 1984.
1017 J.\& L.\& Bentley, L.\& W.\& Jelinski, and B.\& W.\& Kernighan,
1018 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
1019 .I "CHEM \[en] A Program for Typesetting Chemical Structure Diagrams,"
1020 .I "Computers and Chemistry"
1023 Bell Labs, April 1986.
1028 Due to its complex structure, a full
1030 system has many man pages, each describing a single aspect of
1033 Unfortunately, there is no general naming scheme for the documentation
1042 .BR @L_ROFF@ (@MAN1EXT@)
1043 contains a survey of all documentation available in
1047 On other systems, you are on your own, but
1048 .BR troff (@MAN1EXT@)
1049 might be a good starting point.
1056 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
1058 Copyright (C) 2000 - 2004, 2006 - 2008
1059 Free Software Foundation, Inc.
1062 This document is distributed under the terms of the \f[CR]FDL\f[]
1063 (\f[CR]GNU Free Documentation License\f[]) version 1.1 or later.
1065 You should have received a copy of the \f[CR]FDL\f[] on your system,
1066 it is also available on-line at the
1067 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1072 This document was written by