{ "content": [ { "type": "text", "text": "# roff (info)\n\n## NAME\n\nroff - concepts and history of roff typesetting\n\n## DESCRIPTION\n\nroff is the general name for a set of text formatting programs, known\nunder names like troff, nroff, ditroff, groff, etc. A roff system con-\nsists of an extensible text formatting language and a set of programs\nfor printing and converting to other text formats. Unix-like operating\nsystems distribute a roff system as a core package.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **HISTORY**\n- **USING ROFF**\n- **ROFF PROGRAMMING**\n- **FILE NAME EXTENSIONS**\n- **EDITING ROFF**\n- **AUTHORS**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "roff", "section": "", "mode": "info", "summary": "roff - concepts and history of roff typesetting", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "groff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/groff/1/json" }, { "name": "troff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/troff/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 30, "subsections": [] }, { "name": "HISTORY", "lines": 108, "subsections": [] }, { "name": "USING ROFF", "lines": 116, "subsections": [] }, { "name": "ROFF PROGRAMMING", "lines": 52, "subsections": [] }, { "name": "FILE NAME EXTENSIONS", "lines": 25, "subsections": [] }, { "name": "EDITING ROFF", "lines": 82, "subsections": [] }, { "name": "AUTHORS", "lines": 3, "subsections": [] }, { "name": "SEE ALSO", "lines": 99, "subsections": [] } ], "sections": { "NAME": { "content": "roff - concepts and history of roff typesetting\n", "subsections": [] }, "DESCRIPTION": { "content": "roff is the general name for a set of text formatting programs, known\nunder names like troff, nroff, ditroff, groff, etc. A roff system con-\nsists of an extensible text formatting language and a set of programs\nfor printing and converting to other text formats. Unix-like operating\nsystems distribute a roff system as a core package.\n\nThe most common roff system today is the free software implementation\nGNU roff, groff(1). groff implements the look-and-feel and functional-\nity of its ancestors, with many extensions.\n\nThe ancestry of roff is described in section \"History\" below. In this\ndocument, the term roff always refers to the general class of roff pro-\ngrams, not to the roff command provided in early Unix systems.\n\nIn spite of its age, roff is in wide use today, for example, the manual\npages on Unix systems (man pages), many software books, system documen-\ntation, standards, and corporate documents are written in roff. The\nroff output for text devices is still unmatched, and its graphical out-\nput has the same quality as other free type-setting programs and is\nbetter than some of the commercial systems.\n\nroff is used to format Unix manual pages, (or man pages), the standard\ndocumentation system on many Unix-derived operating systems.\n\nThis document describes the history of the development of the roff sys-\ntem; some usage aspects common to all roff versions, details on the\nroff pipeline, which is usually hidden behind front-ends like groff(1);\na general overview of the formatting language; some tips for editing\nroff files; and many pointers to further readings.\n", "subsections": [] }, "HISTORY": { "content": "Document formatting by computer dates back to the 1960s. The roff sys-\ntem itself is intimately connected to the Unix operating system, but\nits roots go back to the earlier operating systems CTSS and Multics.\n\nThe Predecessor RUNOFF\nroff's ancestor RUNOFF was written in the MAD language by Jerry Saltzer\nfor the Compatible Time Sharing System (CTSS), a project of the Massa-\nchusetts Institute of Technology (MIT), in 1963 and 1964--note that\nCTSS commands were all uppercase.\n\nIn 1965, MIT's Project MAC teamed with Bell Telephone Laboratories\n(BTL) and General Electric to begin the Multics system . A command called runoff was written for Multics\nin the late 60s in the BCPL language, by Bob Morris, Doug McIlroy, and\nother members of the Multics team.\n\nLike its CTSS ancestor, Multics runoff formatted an input file consist-\ning of text and command lines; commands began with a period and were\ntwo letters. Output from these commands was to terminal devices such\nas IBM Selectric terminals. Multics runoff had additional features\nadded, such as the ability to do two-pass formatting; it became the\nmain format for Multics documentation and text processing.\n\nBCPL and runoff were ported to the GCOS system at Bell Labs when BTL\nleft the development of Multics.\n\nThere is a free archive about historical RUNOFF documents. You can get\nit anonymously by the shell command\n$git clone https://github.com/bwarken/RUNOFFhistorical.git\n\nAs well, there is a new project for writing a program that can read\nRUNOFF files , but it does not yet work so far. You can get an early\nversion anonymously by the shell command\n$git clone https://github.com/bwarken/runoff.git\n\nThe Classical nroff/troff System\nAt BTL, there was a need to drive the Graphic Systems CAT typesetter, a\ngraphical output device from a PDP-11 computer running Unix. As runoff\nwas too limited for this task it was further developed into a more pow-\nerful text formatting system by Joseph F. Ossanna, who already pro-\ngrammed several runoff ports.\n\nThe name runoff was shortened to roff. The greatly enlarged language\nof Ossanna's version already included all elements of a full roff sys-\ntem. All modern roff systems try to implement compatibility to this\nsystem. So Joe Ossanna can be called the father of all roff systems.\n\nThis first roff system had three formatter programs.\n\ntroff (typesetter roff) generated a graphical output for the CAT type-\nsetter as its only device.\n\nnroff produced text output suitable for terminals and line printers.\n\nroff was the reimplementation of the former runoff program with its\nlimited features; this program was abandoned in later versions.\nToday, the name roff is used to refer to a troff/nroff system as\na whole.\n\nOssanna's first version was written in the PDP-11 assembly language and\nreleased in 1973. Brian Kernighan joined the roff development by\nrewriting it in the C programming language. The C version was released\nin 1975.\n\nThe syntax of the formatting language of the nroff/troff programs was\ndocumented in the famous Troff User's Manual [CSTR #54], first pub-\nlished in 1976, with further revisions up to 1992 by Brian Kernighan.\nThis document is the specification of the classical troff. All later\nroff systems tried to establish compatibility with this specification.\n\nAfter Ossanna's death in 1977, Kernighan went on with developing troff.\nIn the late 1970s, Kernighan equipped troff with a general interface to\nsupport more devices, the intermediate output format, and the postpro-\ncessor system. This completed the structure of a roff system as it is\nstill in use today; see section \"Using Roff\" below. In 1979, these\nnovelties were described in the paper [CSTR #97]. This new troff ver-\nsion is the basis for all existing newer troff systems, including\ngroff. On some systems, this device independent troff got a binary of\nits own, called ditroff(7). All modern troff programs already provide\nthe full ditroff capabilities automatically.\n\nAvailability\nThe source code of both the ancient Unix and classical troff weren't\navailable for two decades. Nowadays, it is accessible again (on-line)\nfor non-commercial use; see SEE ALSO, below.\n\ngroff -- free GNU roff\nThe most important free roff project was the GNU implementation of\ntroff, written from scratch by James Clark and put under the GNU Public\nLicense . It was called groff (GNU roff).\nSee groff(1) for an overview.\n\nThe groff system is still actively developed. It is compatible to the\nclassical troff, but many extensions were added. It is the first roff\nsystem that is available on almost all operating systems -- and it is\nfree. This makes groff the de facto roff standard today.\n\nFree Heirloom roff\nAn alternative is Gunnar Ritter's Heirloom roff project project, started in 2005, which\nprovides enhanced versions of the various roff tools found in the Open-\nSolaris and Plan 9 operating systems, now available under free li-\ncenses. You can get this package with the shell command:\n$ git clone https://github.com/n-t-roff/heirloom-doctools\n\nMoreover, one finds there the Original Documenter's Workbench Release\n3.3 .\n", "subsections": [] }, "USING ROFF": { "content": "Most people won't even notice that they are actually using roff. When\nyou read a system manual page (man page) roff is working in the back-\nground. But using roff explicitly isn't difficult either.\n\nSome roff implementations provide wrapper programs that make it easy to\nuse the roff system on the shell command line. For example, the GNU\nroff implementation groff(1) provides command-line options to avoid the\nlong command pipes of classical troff; a program grog(1) tries to guess\nfrom the document which arguments should be used for a run of groff;\npeople who do not like specifying command-line options should try the\ngroffer(1) program for graphically displaying groff files and man\npages.\n\nThe roff Pipe\nEach roff system consists of preprocessors, roff formatter programs,\nand a set of device postprocessors. This concept makes heavy use of\nthe piping mechanism, that is, a series of programs is called one after\nthe other, where the output of each program in the queue is taken as\nthe input for the next program.\n\ncat file | ... | preproc | ... | troff options | postproc\n\nThe preprocessors generate roff code that is fed into a roff formatter\n(e.g. troff), which in turn generates intermediate output that is fed\ninto a device postprocessor program for printing or final output.\n\nAll of these parts use programming languages of their own; each lan-\nguage is totally unrelated to the other parts. Moreover, roff macro\npackages that were tailored for special purposes can be included.\n\nMost roff documents use the macros of some package, intermixed with\ncode for one or more preprocessors, spiced with some elements from the\nplain roff language. The full power of the roff formatting language is\nseldom needed by users; only programmers of macro packages need to know\nabout the gory details.\n\nPreprocessors\nA roff preprocessor is any program that generates output that syntacti-\ncally obeys the rules of the roff formatting language. Each preproces-\nsor defines a language of its own that is translated into roff code\nwhen run through the preprocessor program. Parts written in these lan-\nguages may be included within a roff document; they are identified by\nspecial roff requests or macros. Each document that is enhanced by\npreprocessor code must be run through all corresponding preprocessors\nbefore it is fed into the actual roff formatter program, for the for-\nmatter just ignores all alien code. The preprocessor programs extract\nand transform only the document parts that are determined for them.\n\nThere are a lot of free and commercial roff preprocessors. Some of\nthem aren't available on each system, but there is a small set of pre-\nprocessors that are considered as an integral part of each roff system.\nThe classical preprocessors are\n\ntbl for tables.\neqn for mathematical formulae.\npic for drawing diagrams.\nrefer for bibliographic references.\nsoelim for including macro files from standard locations.\nchem for drawing chemical formulae.\n\nOther known preprocessors that are not available on all systems include\n\ngrap for constructing graphical elements.\ngrn for including gremlin(1) pictures.\n\nFormatter Programs\nA roff formatter is a program that parses documents written in the roff\nformatting language or uses some of the roff macro packages. It gener-\nates intermediate output, which is intended to be fed into a single de-\nvice postprocessor that must be specified by a command-line option to\nthe formatter program. The documents must have been run through all\nnecessary preprocessors before.\n\nThe output produced by a roff formatter is represented in yet another\nlanguage, the intermediate output format or troff output. This lan-\nguage was first specified in [CSTR #97]; its GNU extension is docu-\nmented in groffout(5). The intermediate output language is a kind of\nassembly language compared to the high-level roff language. The gener-\nated intermediate output is optimized for a special device, but the\nlanguage is the same for every device.\n\nThe roff formatter is the heart of the roff system. The traditional\nroff had two formatters, nroff for text devices and troff for graphical\ndevices.\n\nOften, the name troff is used as a general term to refer to both for-\nmatters.\n\nDevices and Postprocessors\nDevices are hardware interfaces like printers, text or graphical termi-\nnals, etc., or software interfaces such as a conversion into a differ-\nent text or graphical format.\n\nA roff postprocessor is a program that transforms troff output into a\nform suitable for a special device. The roff postprocessors are like\ndevice drivers for the output target.\n\nFor each device there is a postprocessor program that fits the device\noptimally. The postprocessor parses the generated intermediate output\nand generates device-specific code that is sent directly to the device.\n\nThe names of the devices and the postprocessor programs are not fixed\nbecause they greatly depend on the software and hardware abilities of\nthe actual computer. For example, the classical devices mentioned in\n[CSTR #54] have greatly changed since the classical times. The old\nhardware doesn't exist any longer and the old graphical conversions\nwere quite imprecise when compared to their modern counterparts.\n\nFor example, the PostScript device post in classical troff had a reso-\nlution of 720 units per inch, while groff's ps device has 72000, a re-\nfinement of factor 100.\n\nToday the operating systems provide device drivers for most printer-\nlike hardware, so it isn't necessary to write a special hardware post-\nprocessor for each printer.\n", "subsections": [] }, "ROFF PROGRAMMING": { "content": "Documents using roff are normal text files decorated by roff formatting\nelements. The roff formatting language is quite powerful; it is almost\na full programming language and provides elements to enlarge the lan-\nguage. With these, it became possible to develop macro packages that\nare tailored for special applications. Such macro packages are much\nhandier than plain roff. So most people will choose a macro package\nwithout worrying about the internals of the roff language.\n\nMacro Packages\nMacro packages are collections of macros that are suitable to format a\nspecial kind of documents in a convenient way. This greatly eases the\nusage of roff. The macro definitions of a package are kept in a file\ncalled name.tmac (classically tmac.name). All tmac files are stored in\none or more directories at standardized positions. Details on the nam-\ning of macro packages and their placement is found in grofftmac(5).\n\nA macro package that is to be used in a document can be announced to\nthe formatter by the command-line option -m, see troff(1), or it can be\nspecified within a document using the file inclusion requests of the\nroff language, see groff(7).\n\nFamous classical macro packages are man for traditional man pages, mdoc\nfor BSD-style manual pages; the macro sets for books, articles, and\nletters are me (probably from the first name of its creator Eric All-\nman), ms (from Manuscript Macros), and mm (from Memorandum Macros).\n\nThe roff Formatting Language\nThe classical roff formatting language is documented in the Troff\nUser's Manual [CSTR #54]. The roff language is a full programming lan-\nguage providing requests, definition of macros, escape sequences,\nstring variables, number or size registers, and flow controls.\n\nRequests are the predefined basic formatting commands similar to the\ncommands at the shell prompt. The user can define request-like ele-\nments using predefined roff elements. These are then called macros. A\ndocument writer will not note any difference in usage for requests or\nmacros; both are written on a line on their own starting with a dot.\n\nEscape sequences are roff elements starting with a backslash '\\'. They\ncan be inserted anywhere, also in the midst of text in a line. They\nare used to implement various features, including the insertion of non-\nASCII characters with \\(, font changes with \\f, in-line comments with\n\\\", the escaping of special control characters like \\\\, and many other\nfeatures.\n\nStrings are variables that can store a string. A string is stored by\nthe .ds request. The stored string can be retrieved later by the \\*\nescape sequence.\n\nRegisters store numbers and sizes. A register can be set with the re-\nquest .nr and its value can be retrieved by the escape sequence \\n.\n", "subsections": [] }, "FILE NAME EXTENSIONS": { "content": "Manual pages (man pages) take the section number as a file name exten-\nsion, e.g., the filename for this document is roff.7, i.e., it is kept\nin section 7 of the man pages.\n\nThe classical macro packages take the package name as an extension,\ne.g. file.me for a document using the me macro package, file.mm for mm,\nfile.ms for ms, file.pic for pic files, etc.\n\nBut there is no general naming scheme for roff documents, though\nfile.tr for troff file is seen now and then. Maybe there should be a\nstandardization for the filename extensions of roff files.\n\nFile name extensions can be very handy in conjunction with the less(1)\npager. It provides the possibility to feed all input into a command-\nline pipe that is specified in the shell environment variable LESSOPEN.\nThis process is not well documented, so here an example:\n\nLESSOPEN='|lesspipe %s'\n\nwhere lesspipe is either a system supplied command or a shell script of\nyour own.\n\nMore details for file name extensions can be found at grofffile-\nnames(5).\n", "subsections": [] }, "EDITING ROFF": { "content": "All roff formatters provide automated line breaks and horizontal and\nvertical spacing. In order to not disturb this, the following tips can\nbe helpful.\n\no Never include empty or blank lines in a roff document. Instead,\nuse the empty request (a line consisting of a dot only) or a\nline comment .\\\" if a structuring element is needed.\n\no Never start a line with whitespace because this can lead to un-\nexpected behavior. Indented paragraphs can be constructed in a\ncontrolled way by roff requests.\n\no Start each sentence on a line of its own, for the spacing after\na dot is handled differently depending on whether it terminates\nan abbreviation or a sentence. To distinguish both cases, do a\nline break after each sentence.\n\no To additionally use the auto-fill mode in Emacs, it is best to\ninsert an empty roff request (a line consisting of a dot only)\nafter each sentence.\n\nThe following example shows judicious line breaking in a roff input\nfile.\n\nThis is an example of a\n.I roff\ndocument that you can type into your text editor.\n.\nThis is the next sentence in the same paragraph.\n.\nThis is a longer sentence stretching over several input lines;\nabbreviations like cf. are easily identified because the dot is\nnot followed by a line break.\n.\nIn the output, this sentence continues the same paragraph.\n\nEditing with Emacs\nThe best program for editing a roff document is Emacs (or XEmacs); see\nemacs(1). It provides an nroff mode that is suitable for all kinds of\nroff dialects. This mode can be activated by the following methods.\n\nWhen editing a file within Emacs the mode can be changed by typing 'M-x\nnroff-mode', where M-x means to hold down the Meta key (or Alt) and\npress the x key at the same time.\n\nBut it is also possible to have the mode automatically selected when\nthe file is loaded into the editor.\n\no The most general method is to include the following 3 comment\nlines at the end of the file.\n\n.\\\" Local Variables:\n.\\\" mode: nroff\n.\\\" End:\n\no There is a set of file name extensions, e.g. the man pages that\ntrigger the automatic activation of the nroff mode.\n\no Theoretically, it is possible to write the sequence\n\n.\\\" -*- nroff -*-\n\nas the first line of a file to have it started in nroff mode\nwhen loaded. Unfortunately, some applications such as the man\nprogram are confused by this; so this is deprecated.\n\nEditing with Vim\nBesides Emacs, some other editors provide nroff style files too, e.g.\nvim(1), an extension of the vi(1) program. Vim's highlighting can be\nmade to recognize roff files by setting the filetype option in a Vim\nmodeline. For this feature to work, your copy of vim must be built\nwith support for, and configured to enable, several features; consult\nthe editor's online help topics \"auto-setting\", \"filetype\", and \"syn-\ntax\". Then put the following at the end of your roff files, after any\nEmacs configuration:\n\n.\\\" vim: set filetype=groff:\n\nReplace \"groff\" in the above with \"nroff\" if you want highlighing that\ndoes not recognize many of the GNU extensions to roff, such as request,\nregister, and string names longer than two characters.\n", "subsections": [] }, "AUTHORS": { "content": "This document was written by Bernd Warken .\n", "subsections": [] }, "SEE ALSO": { "content": "There is a lot of documentation on roff. The original papers on clas-\nsical troff are still available, and all aspects of groff are docu-\nmented in great detail.\n\nInternet sites\nHistory of Unix Manpages\nThe history page of the\nmdocml project provides an overview of roff development up to\ndate, with links to original documentation and comments of the\noriginal authors.\n\ntroff.org\nThe historical troff site provides an\noverview and pointers to the historical aspects of roff.\n\nMultics\nThe Multics site contains a lot of\ninformation on the MIT projects, CTSS, Multics, early Unix, in-\ncluding runoff; especially useful are a glossary and the many\nlinks to ancient documents.\n\nUnix Archive\nThe Ancient Unixes Archive pro-\nvides the source code and some binaries of the ancient Unixes\n(including the source code of troff and its documentation) that\nwere made public by Caldera since 2001, e.g. of the famous Unix\nversion 7 for PDP-11 at the Unix V7 site .\n\nDevelopers at AT&T Bell Labs\nBell Labs Computing and Mathematical Sciences Research provides a search facility for tracking in-\nformation on the early developers.\n\nPlan 9 The Plan 9 operating system by AT&T\nBell Labs.\n\nrunoff Jerry Saltzer's home page stores some documents using the ancient\nRUNOFF formatting language.\n\nCSTR Papers\nThe Bell Labs (now Alcatel) CSTR site stores the original\ntroff manuals (CSTR #54, #97, #114, #116, #122) and famous his-\ntorical documents on programming.\n\nGNU roff\nThe groff web site provides\nthe free roff implementation groff, the actual standard roff.\n\nHistorical roff Documentation\nMany classical troff documents are still available on-line. The two\nmain manuals of the troff language are\n\n[CSTR #54]\nJ. F. Ossanna, Nroff/Troff User's Manual ; Bell Labs, 1976; revised by Brian Kernighan, 1992.\n\n[CSTR #97]\nBrian Kernighan, A Typesetter-independent TROFF , Bell Labs, 1981, revised\nMarch 1982.\n\nThe \"little language\" roff papers are\n\n[CSTR #114]\nJon L. Bentley and Brian W. Kernighan, GRAP - A Language for\nTypesetting Graphs ; Bell Labs, August 1984.\n\n[CSTR #116]\nBrian W. Kernighan, PIC - A Graphics Language for Typesetting\n; Bell Labs, De-\ncember 1984.\n\n[CSTR #122]\nJ. L. Bentley, L. W. Jelinski, and B. W. Kernighan, CHEM - A\nProgram for Typesetting Chemical Structure Diagrams, Computers\nand Chemistry ;\nBell Labs, April 1986.\n\nYou can get an archive with most classical roff documentation as rea-\nsonable PDF files at github using the shell command\n$ git clone https://github.com/bwarken/roffclassical.git\n\nManual Pages\nDue to its complex structure, a full roff system has many man pages,\neach describing a single aspect of roff. Unfortunately, there is no\ngeneral naming scheme for the documentation among the different roff\nimplementations.\n\nIn groff, the man page groff(1) contains a survey of all documentation\navailable in groff.\n\nOn other systems, you are on your own, but troff(1) might be a good\nstarting point.\n\ngroff 1.22.4 23 March 2022 ROFF(7)", "subsections": [] } } } }