View source for Troff

{{Short description|Typesetting language}}
{{about|the Unix document processing system|the command in BASIC|TROFF|the chess grandmaster|Kayden Troff}}
{{Distinguish|Trough (disambiguation)}}
{{Redirect|tbl||TBL (disambiguation)}}
{{lowercase title}}
{{Missing information|short list of books typeset with troff|date=January 2021}}
{{Infobox software
| name                   = troff
| logo                   = 
| screenshot             = 
| screenshot size        = 
| caption                = 
| author                 = [[Joe Ossanna]]
| developer              = [[AT&T Bell Laboratories]]
| released               = 
| latest release version = 
| latest release date    = 
| programming language   = [[C (programming language)|C]]
| operating system       = [[Unix]], [[Unix-like]], [[Plan 9 from Bell Labs|Plan 9]]
| platform               = [[Cross-platform]]
| genre                  = [[Command (computing)|Command]]
| license                = Plan 9: [[MIT License]]
| website                = 
}}
'''troff''' ({{IPAc-en|ˈ|t|iː|r|ɒ|f}}), short for "typesetter roff", is the major component of a [[document processing system]] developed by [[Bell Labs]] for the [[Unix]] operating system. troff and the related [[nroff]] were both developed from the original [[roff (software)|roff]].

While nroff was intended to produce output on terminals and line printers, troff was intended to produce output on [[typesetting]] systems, specifically the [[CAT (phototypesetter)|Graphic Systems CAT]], which had been introduced in 1972. Both used the same underlying [[markup language]], and a single source file could normally be used by nroff or troff without change.

''troff'' features commands to designate fonts, spacing, paragraphs, margins, footnotes and more. Unlike many other text formatters, ''troff'' can position characters arbitrarily on a page, even overlapping them, and has a fully programmable input language. Separate preprocessors are used for more convenient production of tables, diagrams, and mathematics. Inputs to troff are plain text files and can be created by any text editor.

Extensive [[#macros|macro packages]] have been created for various document styles. A typical distribution of '''troff''' includes the '''me''' macros for formatting research papers, '''man''' and '''mdoc''' macros for creating Unix [[UNIX manual|man pages]], '''mv''' macros for creating mountable [[Overhead projector|transparencies]], and the '''ms''' and '''mm''' macros for letters, books, technical memoranda, and reports.

==History==
''troff'''s origins can be traced to a [[text formatting|text-formatting]] [[computer program|program]] called [[RUNOFF]], which was written by [[Jerome H. Saltzer]] for [[Massachusetts Institute of Technology|MIT]]'s [[Compatible Time-Sharing System|CTSS]] [[operating system]] in the mid-1960s. (The name allegedly came from the phrase ''I'll run off a document''.)

[[Robert Morris (cryptographer)|Bob Morris]] ported it to the [[GE 635]] architecture and called the program [[roff (software)|roff]] (an abbreviation of ''runoff'').{{citation needed|date=February 2020}} It was rewritten as [[rf (program)|rf]] for the [[PDP-7]], and at the same time (1969), [[Doug McIlroy]] rewrote an extended and simplified version of ''roff'' in the [[BCPL]] [[programming language]].

The first version of [[Unix]] was developed on a PDP-7 which was sitting around [[Bell Labs]]. In 1971 the developers wanted to get a [[PDP-11]] for further work on the operating system. In order to justify the cost for this system, they proposed that they would implement a document-formatting system for the Bell Labs patents department.<ref>{{cite book |last=Kernighan |first=B. W. |author-link=Brian Kernighan |date=October 2019 |title=Unix: A History and a Memoir |url=https://www.cs.princeton.edu/~bwk/memoir.html|publisher=Kindle Direct Publishing |page=42 |isbn=9781695978553}}</ref> This first formatting program was a reimplementation of McIllroy's ''roff'', written by [[Joe Ossanna|Joe F. Ossanna]].

When they needed a more flexible language, a new version of ''roff'' called [[nroff]] (''newer "roff"'') was written, which provided the basis for all future versions. When they got a [[CAT (phototypesetter)|Graphic Systems CAT phototypesetter]], Ossanna modified ''nroff'' to support multiple fonts and [[Typeface#Proportion|proportional spacing]]. Dubbed ''troff'', for ''typesetter roff'', its sophisticated output amazed the typesetter manufacturer and confused [[peer review]]ers, who thought that manuscripts using ''troff'' had been published before.<ref>J. F. Ossanna. ''Nroff/Troff User's Manual''.  CSTR #54, Bell Labs, 1976. Revised by B. W. Kernighan, 1992.</ref><ref name="reader">{{cite tech report |first1=M. D. |last1=McIlroy |author-link1=Doug McIlroy |year=1987 |url=http://www.cs.dartmouth.edu/~doug/reader.pdf |title=A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 |series=CSTR |number=139 |institution=Bell Labs}}</ref> As such, the name ''troff'' is pronounced {{IPAc-en|ˈ|t|iː|r|ɒ|f}} rather than *{{IPAc-en|ˈ|t|r|ɒ|f}}.

With ''troff'' came ''nroff'' (they were actually almost the same program), which was for producing output for [[line printer]]s and character [[computer terminal|terminal]]s. It understood everything ''troff'' did, and ignored the commands which were not applicable, e.g., [[typeface|font]] changes.

Ossanna's ''troff'' was written in [[PDP-11]] [[assembly language]] and produced output specifically for the [[CAT (phototypesetter)|CAT phototypesetter]]. He rewrote it in [[C (programming language)|C]], although it was now 7000 lines of uncommented code and still dependent on the CAT. As the CAT became less common, and was no longer supported by the manufacturer, the need to make it support other devices became a priority. Ossanna died before this task was completed, so [[Brian Kernighan]] took on the task of rewriting ''troff''. The newly rewritten version produced a device-independent code which was very easy for post-processors to read and translate to the appropriate printer codes.  Also, this new version of ''troff'' (often called '''ditroff''' for ''device independent troff'') had several extensions, which included drawing functions.<ref>B. W. Kernighan.  ''A Typesetter-Independent TROFF''. CSTR #97, Bell Labs, 1981, revised March 1982.</ref>  The program's documentation defines the output format of ''ditroff'', which is used by many modern ''troff'' clones like GNU [[groff (software)|groff]].

In 1983, ''troff'' was one of several UNIX tools available for Charles River Data Systems' [[UNOS (operating system)|UNOS]] operating system under [[Bell Laboratories]] license.<ref>{{Cite book|year=1983|title=The Insider's Guide To The Universe|publisher=Charles River Data Systems, Inc.|url=https://www.1000bit.it/ad/bro/charles/CharlesRiverSystem-Universe.pdf|page=13}}</ref>

The ''troff'' collection of tools (including [[#Preprocessors|pre]]- and post-processors) was eventually called [[Documenter's WorkBench]] (DWB), and was under continuous development in Bell Labs and later at the spin-off [[Unix System Laboratories]] (USL) through 1994. At that time, [[SoftQuad]] took over the maintenance, although Brian Kernighan continued to improve ''troff'' on his own. Thus, there are at least the following variants of the original Bell Labs ''troff'' in use:

* the SoftQuad DWB, based on USL DWB 2.0 from 1994;
* the DWB 3.4 from [[Lucent]] Software Solutions (formerly USL);
* troff, [[Plan 9 from Bell Labs|Plan 9]] edition.

While ''troff'' has been supplanted by other programs such as [[Interleaf]], [[FrameMaker]], and [[LaTeX]], it is still being used quite extensively. It remains the default formatter for the [[UNIX manual|UNIX documentation]].

The software was reimplemented as [[groff (software)|groff]] for the [[GNU's Not Unix|GNU]] system beginning in 1990. In addition, due to the [[open-source software|open sourcing]] of [[Ancient UNIX]] systems, as well as modern successors such as the ditroff-based open-sourced versions found on [[OpenSolaris]] and [[Plan 9 from Bell Labs]], there are several versions of AT&T troff (CAT and ditroff-based<ref>See the man page of the ditroff -> postscript converter on OpenSolaris: {{man|1|dpost|OpenSolaris}}</ref>) available under various open-source licenses.

== Macros ==
In general, one was not encouraged to use troff directly, but rather go through some easier-to-use interface.<ref>{{cite book | title=Troff Typesetting for UNIX Systems ·| first1=Sandra L. | last1=Emerson | first2=Karen | last2=Paulsell | year=1987 | page =9 | publisher=Prentice-Hall | location=Englewood Cliffs, New Jersey}}</ref><ref name="gehani">{{cite book | first=Narain | last=Gehani | title=Document Formatting and Typesetting on the UNIX System | publisher=Silicon Press | location=Summit, New Jersey  | edition=Second | year=1992  | pages=11&ndash;12 | isbn=978-0-9615336-2-5 | url=https://books.google.com/books?id=Wz1C5JhTzlYC&q=-m&pg=PA15 }}</ref>
Troff includes '''macros''' that are run before starting to process the document. These macros include setting up page headers and footers, defining new commands, and influencing how the output will be formatted. The [[command-line argument]] for including a macro set is <code>''-m'''''name'''</code>, which has led to many macro sets being known as the base filename with a leading '''m'''.<ref>{{cite web | url=https://www.stephenlindholm.com/groff_macros.html | title=groff/troff macros: ms, mm, me or mom | first=Stephen | last=Lindholm | publisher=... | access-date=June 3, 2024}}</ref>

The standard macro sets, with leading '''m''' are:

* '''man''' for creating [[Unix manual|manual]] pages<ref>{{cite web |title=Writing and Formmating UNIX Manual Pages with -man macros |url=http://home.fnal.gov/~mengel/man_page_notes.html |website=home.fnal.gov |access-date=7 May 2019}}</ref><ref>{{man|7|man|ManKier}}</ref>
* '''mdoc''' for semantically annotated [[Unix manual|manual]] pages, which are better adapted to [[mandoc]] conversion to other formats.<ref>{{man|7|mdoc|FreeBSD}}</ref><ref>{{cite web |title=Index - Mandoc extended documentation |url=http://mandoc.bsd.lv/mdoc/ |website=Mandoc |access-date=7 May 2019}}</ref> <code>mandoc</code> is a fusion that supports both sets of manual commands.<ref name=tmac/>
* '''me''' for creating research papers<ref>{{man|7|groff_me|ManKier}}</ref>
* '''mm''' for creating [[memorandum]]s<ref>{{man|7|groff_mm|ManKier}}</ref>
* '''ms''' for creating books, reports, and technical documentation<ref>{{man|7|groff_ms|ManKier}}</ref>

The ms macros were the first of these, developed at AT&T, before they were supplanted by the mm macros.<ref name="Srinivasan"/> One goal of the mm macros was that they be usable by the [[typing pool]] at Bell Labs and, over time, this happened and the mm macros became a standard at Bell Labs.<ref name="oh-mashey">{{cite interview | url=https://archive.computerhistory.org/resources/access/text/2018/10/102738835-05-01-acc.pdf  | title=Oral History of John Mashey | first=John| last=Mashey | interviewer=John Markoff | editor=Dag Spicer | publisher=Computer History Museum | location=Mountain View, California | date=July 18, 2018 | pages=27–29, 37 | access-date=May 26, 2024 }}</ref>  AT&T made the mm macros commercially available for System V Unix.<ref name="Srinivasan"/> In contrast, the me macros were developed at Berkeley.<ref name="Srinivasan">{{cite book | first=B. | last=Srinivasan | title=UNIX Document Processing and Typesetting | publisher=World Scientific | location=Singapore | year=1993 | pages= 11–12  | isbn=978-981-02-0605-5 | url=https://books.google.com/books?id=VKPBHCWTCGEC&q=unix+document+processing+and+typesetting+hound}}</ref>

An example of a simple business letter prepared with the mm macros would be:

{{pre|
{{codett|2=groff|.TL}}
{{codett|2=groff|.ND "January 10, 1993"}}
{{codett|2=groff|.AU "Ms. Jane Smith"}}
{{codett|2=groff|.AT "Upcoming appointment"}}
{{codett|2=groff|.MT 5}}
Reference #A12345
{{codett|2=groff|.sp 4}}
Mr. Samuel Jones
{{codett|2=groff|.sp 0}}
Field director, Bureau of Inspections
{{codett|2=groff|.sp 0}}
1010 Government Plaza
{{codett|2=groff|.sp 0}}
Capitoltown, ST
{{codett|2=groff|.sp 3}}
Dear Mr. Jones,
{{codett|2=groff|.sp 2}}
{{codett|2=groff|.P}}
Making reference to the noted obligation to submit for state inspection our newly created production process, we request that you consider the possible inappropriateness of subjecting the  innovative technologies of tomorrow to the largely antiquated requirements of yesterday.  If our great state is to prosper in the twenty-first century, we must take steps 
{{codett|2=groff|.B}} now ,
in 
{{codett|2=groff|.I}} this 
year of 
{{codett|2=groff|.I}} this 
decade, to prepare our industrial base for the interstate and international competition that is sure to appear.  Our new process does precisely that.  Please do not let it be undone by a regulatory environment that is no longer apt.
{{codett|2=groff|.P}}
Thank you for your consideration of our position.
{{codett|2=groff|.FC Sincerely}}
{{codett|2=groff|.SG}}
}}

A comprehensive list of macros available is usually listed in a <code>tmac(5)</code> [[manual page]].<ref name=tmac>{{man|5|groff_tmac|ManKier}}</ref>

==Preprocessors==
As ''troff'' evolved, since there are several things which cannot be done easily in ''troff'', several [[preprocessor]]s were developed. These programs transform certain parts of a document into ''troff'' input, fitting naturally into the use of "pipelines" in Unix — sending the output of one program as the input to another (see [[pipes and filters]]).  Typically, each preprocessor translates only sections of the input file that are specially marked, passing the rest of the file through unchanged.  The embedded preprocessing instructions are written in a simple application-specific programming language, which provides a high degree of power and flexibility.

* [[eqn (software)|eqn]] preprocessor allows mathematical formulae to be specified in simple and intuitive manner.<ref>B. W. Kernighan and Lorinda L. Cherry.  ''A System for Typesetting Mathematics''. CSTR #17, Bell Labs, May 1974.</ref>
* tbl is a preprocessor for formatting tables.
* [[refer (software)|refer]] (and the similar program ''bib'') processes citations in a document according to a [[bibliographic]] database.

Three preprocessors provide ''troff'' with drawing capabilities by defining a [[domain-specific language]] for describing the picture.
* ''[[pic (software)|pic]]'' is a [[procedural programming language]] providing various drawing functions like ''circle'' and ''box''.<ref>B. W. Kernighan.  ''PIC — A Graphics Language for Typesetting (Revised User Manual)''.  CSTR #116, Bell Labs, December 1984.</ref>
* ''ideal'' allows the drawing of pictures [[Declarative programming|declaratively]], deriving the picture by solving a system of [[simultaneous equations]] based on vectors and transformations described by its input.<ref>C. J. Van Wyk.  ''IDEAL User's Manual''. CSTR #103, Bell Labs, December 1981.</ref>
* ''grn'' describes the pictures through graphical elements drawn at absolute coordinates, based on the ''[[gremlin (file format)|gremlin file format]]'' defined by an early graphics workstation.<ref>grn — groff preprocessor for gremlin files [http://www.unix.com/man-page/All/1/grn/].</ref>

In addition, there is a command [[soelim]] that removes <code>.so</code> inclusion directives from the input text.<ref name="oreilly-quick-svr4"/>

A typical structure of the pipeline might be:

<code>soelim <i>file</i> | refer | ideal | pic | tbl | eqn | troff</code>

Yet more preprocessors allow the drawing of more complex pictures by generating output for ''pic''.
* ''grap'' draws [[chart]]s, like [[scatter plots]] and [[histograms]].<ref>J. L. Bentley and B. W. Kernighan.  ''GRAP — A Language for Typesetting Graphs (Tutorial and User Manual)''. CSTR #114, Bell Labs, August 1984.</ref>
* ''chem'' draws [[structural formula|chemical structure diagrams]].<ref>J. L. Bentley, L. W. Jelinski, and B. W. Kernighan. ''CHEM — A Program for Typesetting Chemical Structure Diagrams''. CSTR #122, Computers and Chemistry, Bell Labs, April 1986.</ref>
* ''dformat'' draws [[row (database)|record-based]] [[data structures]].<ref>J. L. Bentley.  ''DFORMAT — A Program for Typesetting Data Formats''. CSTR #142, Bell Labs, April 1988.</ref>

== Other front-ends ==
Several other front-ends have been developed that are intended to be friendlier interfaces to troff.  

One of them is '''Sanscribe''', originally developed at Berkeley and then enhanced during the 1980s by several users including [[Intel]] and  [[Advanced_Computer_Techniques#InterACT|InterACT]].  Used for writing memos, reports, documents, Sanscribe is built upon basic troff commands as well as the me macros and various pre- and post-processors such as soelim, eqn, tbl, grap, and pic. However it is a main program binary, not a preprocessor.  The conditional inclusion capability renders it especially useful for maintaining multi-platform reference manuals. However, Sanscribe is fragile and prone to giving  cryptic errors or producing weirdly formatted results.<ref name="sanscribe">{{cite book | title=Sanscribe: User's Guide and Reference | publisher=... | edition=Revision 3.0 | date=January 13, 1989 | pages=1-1, 2-1, 3-2, 6-1 }}</ref>

A special-purpose front-end is '''vgrind''', which generates nicely formatted source program listings, with such features as putting comments in italics, keywords in bold, and function names highlighted in margins. It can run either as a filter or as a main program with its output being passed to troff. It has support for the languages in use at Bell Labs facilities, including not just [[Fortran]], [[C programming language|C]], and [[C++ programming language|C++]] but also domain-specific tools such as [[Bourne shell]] and [[yacc]] as well as those further afield such as [[Emacs Lisp]] and [[Icon (programming language)|Icon]].<ref name="oreilly-quick-svr4">{{cite book | url=https://books.google.com/books?id=hjSqwEKIyOAC&pg=PA187 | title=UNIX in a Nutshell: A Desktop Quick Reference for System V Release 4 and Solaris 7 | first=Arnold | last=Robbins | publisher=O'Reilly Media | edition=Third | location=Sebastopol, California | year=1999 | pages=151, 187–189 | isbn=978-1-56592-427-7 }}</ref>

A different approach is employed by the '''CADiZ''' suite of tools for the [[Z notation]].  Rather than the <code>cadiz</code> program being a preprocessor in the front of the pipeline, it interacts multiple times with <code>troff</code> as both input and output, using saved files rather than a pipe. CADiZ also contains its own set of macros, called <code>.ZA</code> to <code>.ZZ</code>.<ref name="cadiz">{{cite conference | url=https://books.google.com/books?id=nSHUBwAAQBAJ&dq=cadiz+soelim+eqn+tbl+pic&pg=PA95 | first1=David | last1=Jordan | first2=John A. | last2=McDermid | first3=Ian | last3=Toyn | year=1991 | title=CADi<math>\mathbb{Z}</math> &ndash; Computer Aided Design in Z | conference=Z User Workshop, Oxford 1990: Proceedings of the Fifth Annual Z User Meeting, Oxford: 17&ndash;18 December 1990 | editor-first=J. E. | editor-last=Nicholls| publisher=Springer-Verlag | location=Berlin, Heidelberg | pages= 93–104 }}</ref>

==See also==
*[[Desktop publishing]]
*[[DocBook]]
*[[groff (software)|groff]] GNU troff/nroff replacement
*[[nroff]]
*[[SGML]]
*[[TeX]]
*[[Scribe (markup language)]]

==References==
{{Reflist}}

==External links==
* [http://troff.org/ The Text Processor for Typesetters]
* [http://www.troff.org/history.html The history of troff]
* [https://www.gnu.org/software/groff Free troff implementation]
* [https://heirloom.sourceforge.net/doctools.html OpenSolaris-derived port of troff and related programs]
* [https://9p.io/sys/doc/troff.ps User manual for the Plan 9 edition of troff] (In PostScript format)
* [http://www.darwinsys.com/history/hist.html A History of UNIX before Berkeley] section 3 describes the history of roff, nroff, troff, ditroff, tbl, eqn, and more.
* The original source code of nroff, troff and the preprocessors from AT&T Bell Labs in form of the [https://github.com/n-t-roff/DWB3.3 Documenter's Workbench (DWB) Release 3.3] (ported to current UNIX systems from http://www2.research.att.com/sw/download)

{{Document markup languages}}
{{Plan 9 commands}}

[[Category:Troff| ]]
[[Category:Free typesetting software]]
[[Category:Page description languages]]
[[Category:History of software]]
[[Category:Plan 9 commands]]
[[Category:Unix text processing utilities]]