# roff(7) - man - phpMan [ROFF(7)](https://www.chedong.com/phpMan.php/man/ROFF/7/markdown) Miscellaneous Information Manual [ROFF(7)](https://www.chedong.com/phpMan.php/man/ROFF/7/markdown) ## NAME roff - concepts and history of roff typesetting ## DESCRIPTION _roff_ is the general name for a set of text formatting programs, known under names like **troff**, **nroff**, **ditroff**, **groff**, etc. A _roff_ system consists of an extensible text formatting language and a set of programs for printing and converting to other text formats. Unix-like operating systems distribute a _roff_ system as a core package. The most common _roff_ system today is the free software implementation GNU _roff_, [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). _groff_ implements the look-and-feel and functionality of its ancestors, with many extensions. The ancestry of _roff_ is described in section “History” below. In this document, the term _roff_ always refers to the general class of roff programs, not to the **roff** command provided in early Unix systems. In spite of its age, _roff_ is in wide use today, for example, the manual pages on Unix systems (_man_ _pages_), many software books, system documentation, standards, and corporate documents are written in roff. The _roff_ output for text devices is still unmatched, and its graphical output has the same quality as other free type-setting programs and is better than some of the commercial systems. _roff_ is used to format Unix _manual_ _pages_, (or _man_ _pages_), the standard documentation system on many Unix-derived operating systems. This document describes the history of the development of the _roff_ _system_; some usage aspects common to all _roff_ versions, details on the _roff_ pipeline, which is usually hidden behind front-ends like [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown); a general overview of the formatting language; some tips for edit‐ ing _roff_ files; and many pointers to further readings. ## HISTORY Document formatting by computer dates back to the 1960s. The _roff_ system itself is inti‐ mately connected to the Unix operating system, but its roots go back to the earlier operating systems CTSS and Multics. ### The Predecessor RUNOFF **roff**'s ancestor **RUNOFF** was written in the MAD language by _Jerry_ _Saltzer_ for the _Compatible_ _Time_ _Sharing_ _System_ _(CTSS)_, a project of the Massachusetts Institute of Technology (MIT), in 1963 and 1964—note that CTSS commands were all uppercase. In 1965, MIT's Project MAC teamed with Bell Telephone Laboratories (BTL) and General Electric to begin the _Multics_ system ⟨⟩. A command called **runoff** was written for Multics in the late 60s in the BCPL language, by _Bob_ _Morris_, _Doug_ _McIlroy_, and other mem‐ bers of the Multics team. Like its CTSS ancestor, Multics **runoff** formatted an input file consisting of text and command lines; commands began with a period and were two letters. Output from these commands was to terminal devices such as IBM Selectric terminals. Multics **runoff** had additional features added, such as the ability to do two-pass formatting; it became the main format for Multics documentation and text processing. BCPL and **runoff** were ported to the GCOS system at Bell Labs when BTL left the development of Multics. There is a free archive about _historical_ _RUNOFF_ documents. You can get it anonymously by the shell command $git clone As well, there is a new project for writing a program that can read _RUNOFF_ _files_ _,_ but it does not yet work so far. You can get an early version anonymously by the shell command $git clone ### The Classical nroff/troff System At BTL, there was a need to drive the _Graphic_ _Systems_ _CAT_ typesetter, a graphical output de‐ vice from a PDP-11 computer running Unix. As **runoff** was too limited for this task it was further developed into a more powerful text formatting system by _Joseph_ _F._ _Ossanna_, who al‐ ready programmed several runoff ports. The name _runoff_ was shortened to _roff_. The greatly enlarged language of Ossanna's version already included all elements of a full _roff_ _system_. All modern _roff_ systems try to imple‐ ment compatibility to this system. So Joe Ossanna can be called the father of all _roff_ sys‐ tems. This first _roff_ _system_ had three formatter programs. **troff** (_typesetter_ _roff_) generated a graphical output for the _CAT_ typesetter as its only de‐ vice. **nroff** produced text output suitable for terminals and line printers. **roff** was the reimplementation of the former **runoff** program with its limited features; this program was abandoned in later versions. Today, the name _roff_ is used to refer to a _troff/nroff_ system as a whole. Ossanna's first version was written in the PDP-11 assembly language and released in 1973. _Brian_ _Kernighan_ joined the _roff_ development by rewriting it in the C programming language. The C version was released in 1975. The syntax of the formatting language of the **nroff**/**troff** programs was documented in the fa‐ mous _Troff_ _User's_ _Manual_ [CSTR #54], first published in 1976, with further revisions up to 1992 by Brian Kernighan. This document is the specification of the _classical_ _troff_. All later _roff_ systems tried to establish compatibility with this specification. After Ossanna's death in 1977, Kernighan went on with developing _troff_. In the late 1970s, Kernighan equipped _troff_ with a general interface to support more devices, the intermediate output format, and the postprocessor system. This completed the structure of a _roff_ _system_ as it is still in use today; see section “Using Roff” below. In 1979, these novelties were described in the paper [CSTR #97]. This new _troff_ version is the basis for all existing newer troff systems, including _groff_. On some systems, this _device_ _independent_ _troff_ got a binary of its own, called [**ditroff**(7)](https://www.chedong.com/phpMan.php/man/ditroff/7/markdown). All modern **troff** programs already provide the full **ditroff** capabilities automatically. ### Availability The source code of both the ancient Unix and classical _troff_ weren't available for two decades. Nowadays, it is accessible again (on-line) for non-commercial use; see **SEE** **ALSO**, below. **groff** —— **free** **GNU** **roff** The most important free _roff_ project was the GNU implementation of _troff_, written from scratch by _James_ _Clark_ and put under the GNU Public License ⟨⟩. It was called _groff_ (GNU _roff_). See [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) for an overview. The _groff_ system is still actively developed. It is compatible to the classical _troff_, but many extensions were added. It is the first _roff_ system that is available on almost all op‐ erating systems — and it is free. This makes _groff_ the de facto _roff_ standard today. ### Free Heirloom roff An alternative is _Gunnar_ _Ritter's_ _Heirloom_ _roff_ _project_ ⟨ heirloom-doctools⟩ project, started in 2005, which provides enhanced versions of the various roff tools found in the OpenSolaris and Plan 9 operating systems, now available under free licenses. You can get this package with the shell command: $ git clone Moreover, one finds there the _Original_ _Documenter's_ _Workbench_ _Release_ _3.3_ ⟨https:// github.com/n-t-roff/DWB3.3⟩. ## USING ROFF Most people won't even notice that they are actually using _roff_. When you read a system man‐ ual page (man page) _roff_ is working in the background. But using _roff_ explicitly isn't dif‐ ficult either. Some _roff_ implementations provide wrapper programs that make it easy to use the _roff_ system on the shell command line. For example, the GNU _roff_ implementation [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) provides com‐ mand-line options to avoid the long command pipes of classical _troff_; a program [**grog**(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) tries to guess from the document which arguments should be used for a run of **groff**; people who do not like specifying command-line options should try the [**groffer**(1)](https://www.chedong.com/phpMan.php/man/groffer/1/markdown) program for graphically displaying _groff_ files and man pages. ### The roff Pipe Each _roff_ system consists of preprocessors, _roff_ formatter programs, and a set of device postprocessors. This concept makes heavy use of the _piping_ mechanism, that is, a series of programs is called one after the other, where the output of each program in the queue is taken as the input for the next program. cat _file_ | ... | _preproc_ | ... | troff _options_ | _postproc_ The preprocessors generate _roff_ code that is fed into a _roff_ formatter (e.g. **troff**), which in turn generates _intermediate_ _output_ that is fed into a device postprocessor program for print‐ ing or final output. All of these parts use programming languages of their own; each language is totally unrelated to the other parts. Moreover, _roff_ macro packages that were tailored for special purposes can be included. Most _roff_ documents use the macros of some package, intermixed with code for one or more pre‐ processors, spiced with some elements from the plain _roff_ language. The full power of the _roff_ formatting language is seldom needed by users; only programmers of macro packages need to know about the gory details. ### Preprocessors A _roff_ preprocessor is any program that generates output that syntactically obeys the rules of the _roff_ formatting language. Each preprocessor defines a language of its own that is translated into _roff_ code when run through the preprocessor program. Parts written in these languages may be included within a _roff_ document; they are identified by special _roff_ re‐ quests or macros. Each document that is enhanced by preprocessor code must be run through all corresponding preprocessors before it is fed into the actual _roff_ formatter program, for the formatter just ignores all alien code. The preprocessor programs extract and transform only the document parts that are determined for them. There are a lot of free and commercial _roff_ preprocessors. Some of them aren't available on each system, but there is a small set of preprocessors that are considered as an integral part of each _roff_ system. The classical preprocessors are **tbl** for tables. **eqn** for mathematical formulae. **pic** for drawing diagrams. **refer** for bibliographic references. **soelim** for including macro files from standard locations. **chem** for drawing chemical formulæ. Other known preprocessors that are not available on all systems include **grap** for constructing graphical elements. **grn** for including [**gremlin**(1)](https://www.chedong.com/phpMan.php/man/gremlin/1/markdown) pictures. ### Formatter Programs A _roff_ _formatter_ is a program that parses documents written in the _roff_ formatting language or uses some of the _roff_ macro packages. It generates _intermediate_ _output_, which is intended to be fed into a single device postprocessor that must be specified by a command-line option to the formatter program. The documents must have been run through all necessary preproces‐ sors before. The output produced by a _roff_ formatter is represented in yet another language, the _interme__‐ _diate_ _output_ _format_ or _troff_ _output_. This language was first specified in [CSTR #97]; its GNU extension is documented in **groff**___**[out**(5)](https://www.chedong.com/phpMan.php/man/out/5/markdown). The intermediate output language is a kind of assembly language compared to the high-level _roff_ language. The generated intermediate out‐ put is optimized for a special device, but the language is the same for every device. The _roff_ formatter is the heart of the _roff_ system. The traditional _roff_ had two formatters, **nroff** for text devices and **troff** for graphical devices. Often, the name _troff_ is used as a general term to refer to both formatters. ### Devices and Postprocessors Devices are hardware interfaces like printers, text or graphical terminals, etc., or software interfaces such as a conversion into a different text or graphical format. A _roff_ postprocessor is a program that transforms _troff_ output into a form suitable for a special device. The _roff_ postprocessors are like device drivers for the output target. For each device there is a postprocessor program that fits the device optimally. The post‐ processor parses the generated intermediate output and generates device-specific code that is sent directly to the device. The names of the devices and the postprocessor programs are not fixed because they greatly depend on the software and hardware abilities of the actual computer. For example, the clas‐ sical devices mentioned in [CSTR #54] have greatly changed since the classical times. The old hardware doesn't exist any longer and the old graphical conversions were quite imprecise when compared to their modern counterparts. For example, the PostScript device _post_ in classical _troff_ had a resolution of 720 units per inch, while _groff_'s _ps_ device has 72000, a refinement of factor 100. Today the operating systems provide device drivers for most printer-like hardware, so it isn't necessary to write a special hardware postprocessor for each printer. ## ROFF PROGRAMMING Documents using _roff_ are normal text files decorated by _roff_ formatting elements. The _roff_ formatting language is quite powerful; it is almost a full programming language and provides elements to enlarge the language. With these, it became possible to develop macro packages that are tailored for special applications. Such macro packages are much handier than plain _roff_. So most people will choose a macro package without worrying about the internals of the _roff_ language. ### Macro Packages Macro packages are collections of macros that are suitable to format a special kind of docu‐ ments in a convenient way. This greatly eases the usage of _roff_. The macro definitions of a package are kept in a file called _name_**.tmac** (classically **tmac.**_name_). All tmac files are stored in one or more directories at standardized positions. Details on the naming of macro packages and their placement is found in **groff**___**[tmac**(5)](https://www.chedong.com/phpMan.php/man/tmac/5/markdown). A macro package that is to be used in a document can be announced to the formatter by the command-line option **-m**, see [**troff**(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown), or it can be specified within a document using the file inclusion requests of the _roff_ language, see [**groff**(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown). Famous classical macro packages are _man_ for traditional man pages, _mdoc_ for BSD-style manual pages; the macro sets for books, articles, and letters are _me_ (probably from the first name of its creator _Eric_ Allman), _ms_ (from _Manuscript_ _Macros_), and _mm_ (from _Memorandum_ _Macros_). ### The roff Formatting Language The classical _roff_ formatting language is documented in the _Troff_ _User's_ _Manual_ [CSTR #54]. The _roff_ language is a full programming language providing requests, definition of macros, escape sequences, string variables, number or size registers, and flow controls. _Requests_ are the predefined basic formatting commands similar to the commands at the shell prompt. The user can define request-like elements using predefined _roff_ elements. These are then called _macros_. A document writer will not note any difference in usage for requests or macros; both are written on a line on their own starting with a dot. _Escape_ _sequences_ are _roff_ elements starting with a backslash ‘**\**’. They can be inserted any‐ where, also in the midst of text in a line. They are used to implement various features, in‐ cluding the insertion of non-ASCII characters with **\(**, font changes with **\f**, in-line comments with **\"**, the escaping of special control characters like **\\**, and many other features. _Strings_ are variables that can store a string. A string is stored by the **.ds** request. The stored string can be retrieved later by the **\*** escape sequence. _Registers_ store numbers and sizes. A register can be set with the request **.nr** and its value can be retrieved by the escape sequence **\n**. ## FILE NAME EXTENSIONS Manual pages (man pages) take the section number as a file name extension, e.g., the filename for this document is _roff.7_, i.e., it is kept in section 7 of the man pages. The classical macro packages take the package name as an extension, e.g. _file._**me** for a docu‐ ment using the _me_ macro package, _file._**mm** for _mm_, _file._**ms** for _ms_, _file._**pic** for _pic_ files, etc. But there is no general naming scheme for _roff_ documents, though _file._**tr** for _troff_ _file_ is seen now and then. Maybe there should be a standardization for the filename extensions of _roff_ files. File name extensions can be very handy in conjunction with the [**less**(1)](https://www.chedong.com/phpMan.php/man/less/1/markdown) pager. It provides the possibility to feed all input into a command-line pipe that is specified in the shell en‐ vironment variable **LESSOPEN**. This process is not well documented, so here an example: LESSOPEN='|lesspipe %s' where **lesspipe** is either a system supplied command or a shell script of your own. More details for _file_ _name_ _extensions_ can be found at **groff**___**[filenames**(5)](https://www.chedong.com/phpMan.php/man/filenames/5/markdown). ## EDITING ROFF All _roff_ formatters provide automated line breaks and horizontal and vertical spacing. In order to not disturb this, the following tips can be helpful. • Never include empty or blank lines in a _roff_ document. Instead, use the empty request (a line consisting of a dot only) or a line comment **.\"** if a structuring element is needed. • Never start a line with whitespace because this can lead to unexpected behavior. In‐ dented paragraphs can be constructed in a controlled way by _roff_ requests. • Start each sentence on a line of its own, for the spacing after a dot is handled dif‐ ferently depending on whether it terminates an abbreviation or a sentence. To distin‐ guish both cases, do a line break after each sentence. • To additionally use the auto-fill mode in Emacs, it is best to insert an empty _roff_ request (a line consisting of a dot only) after each sentence. The following example shows judicious line breaking in a _roff_ input file. This is an example of a .I roff document that you can type into your text editor. . This is the next sentence in the same paragraph. . This is a longer sentence stretching over several input lines; abbreviations like cf. are easily identified because the dot is not followed by a line break. . In the output, this sentence continues the same paragraph. ### Editing with Emacs The best program for editing a _roff_ document is Emacs (or XEmacs); see [**emacs**(1)](https://www.chedong.com/phpMan.php/man/emacs/1/markdown). It provides an _nroff_ mode that is suitable for all kinds of _roff_ dialects. This mode can be activated by the following methods. When editing a file within Emacs the mode can be changed by typing ‘_M-x_ _nroff-mode_’, where **M-** **x** means to hold down the **Meta** key (or **Alt**) and press the **x** key at the same time. But it is also possible to have the mode automatically selected when the file is loaded into the editor. • The most general method is to include the following 3 comment lines at the end of the file. .\" Local Variables: .\" mode: nroff .\" End: • There is a set of file name extensions, e.g. the man pages that trigger the automatic activation of the _nroff_ mode. • Theoretically, it is possible to write the sequence .\" -*- nroff -*- as the first line of a file to have it started in _nroff_ mode when loaded. Unfortu‐ nately, some applications such as the **man** program are confused by this; so this is deprecated. ### Editing with Vim Besides Emacs, some other editors provide _nroff_ style files too, e.g. [**vim**(1)](https://www.chedong.com/phpMan.php/man/vim/1/markdown), an extension of the [**vi**(1)](https://www.chedong.com/phpMan.php/man/vi/1/markdown) program. Vim's highlighting can be made to recognize _roff_ files by setting the _filetype_ option in a Vim _modeline_. For this feature to work, your copy of **vim** must be built with support for, and configured to enable, several features; consult the editor's online help topics “auto-setting”, “filetype”, and “syntax”. Then put the following at the end of your _roff_ files, after any Emacs configuration: .\" vim: set filetype=groff: Replace “groff” in the above with “nroff” if you want highlighing that does _not_ recognize many of the GNU extensions to _roff_, such as request, register, and string names longer than two characters. ## AUTHORS This document was written by Bernd Warken ⟨⟩. ## SEE ALSO There is a lot of documentation on _roff_. The original papers on classical _troff_ are still available, and all aspects of _groff_ are documented in great detail. ### Internet sites History of Unix Manpages The history page ⟨⟩ of the mdocml project provides an overview of _roff_ development up to date, with links to original documentation and comments of the original authors. troff.org The historical troff site ⟨⟩ provides an overview and pointers to the historical aspects of _roff_. Multics The Multics site ⟨⟩ contains a lot of information on the MIT projects, CTSS, Multics, early Unix, including _runoff_; especially useful are a glos‐ sary and the many links to ancient documents. Unix Archive The Ancient Unixes Archive ⟨⟩ provides the source code and some binaries of the ancient Unixes (including the source code of _troff_ and its docu‐ mentation) that were made public by Caldera since 2001, e.g. of the famous Unix ver‐ sion 7 for PDP-11 at the Unix V7 site ⟨⟩. Developers at AT&T Bell Labs Bell Labs Computing and Mathematical Sciences Research ⟨⟩ provides a search facility for tracking information on the early developers. Plan 9 The Plan 9 operating system ⟨⟩ by AT&T Bell Labs. runoff Jerry Saltzer's home page ⟨⟩ stores some documents using the ancient RUNOFF formatting language. CSTR Papers The Bell Labs (now Alcatel) CSTR site ⟨ bell-labs-journals⟩ stores the original _troff_ manuals (CSTR #54, #97, #114, #116, #122) and famous historical documents on programming. GNU _roff_ The groff web site ⟨⟩ provides the free _roff_ imple‐ mentation _groff_, the actual standard _roff_. ### Historical roff Documentation Many classical **troff** documents are still available on-line. The two main manuals of the _troff_ language are [CSTR #54] J. F. Ossanna, _Nroff/Troff_ _User's_ _Manual_ ⟨⟩; Bell Labs, 1976; revised by Brian Kernighan, 1992. [CSTR #97] Brian Kernighan, _A_ _Typesetter-independent_ _TROFF_ ⟨ 97.ps.gz⟩, Bell Labs, 1981, revised March 1982. The “little language” _roff_ papers are [CSTR #114] Jon L. Bentley and Brian W. Kernighan, _GRAP_ _– _A_ _Language_ _for_ _Typesetting_ _Graphs_ ⟨⟩; Bell Labs, August 1984. [CSTR #116] Brian W. Kernighan, _PIC_ _– _A_ _Graphics_ _Language_ _for_ _Typesetting_ ⟨http:// cm.bell-labs.com/cm/cs/cstr/116.ps.gz⟩; Bell Labs, December 1984. [CSTR #122] J. L. Bentley, L. W. Jelinski, and B. W. Kernighan, _CHEM_ _– _A_ _Program_ _for_ _Typesetting_ _Chemical_ _Structure_ _Diagrams,_ _Computers_ _and_ _Chemistry_ ⟨ cstr/122.ps.gz⟩; Bell Labs, April 1986. You can get an archive with most _classical_ _roff_ _documentation_ as reasonable _PDF_ _files_ at _github_ using the _shell_ _command_ $ git clone ### Manual Pages Due to its complex structure, a full _roff_ system has many man pages, each describing a single aspect of _roff_. Unfortunately, there is no general naming scheme for the documentation among the different _roff_ implementations. In _groff_, the man page [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) contains a survey of all documentation available in _groff_. On other systems, you are on your own, but [**troff**(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) might be a good starting point. groff 1.22.4 23 March 2022 [ROFF(7)](https://www.chedong.com/phpMan.php/man/ROFF/7/markdown)