1ROFF(7)                Miscellaneous Information Manual                ROFF(7)
2
3
4

NAME

6       roff - concepts and history of roff typesetting
7

DESCRIPTION

9       roff  is  the general name for a set of text formatting programs, known
10       under names like troff, nroff, ditroff, groff, etc.  A roff system con‐
11       sists  of  an extensible text formatting language and a set of programs
12       for printing and converting to other text formats.  Unix-like operating
13       systems distribute a roff system as a core package.
14
15       The  most  common roff system today is the free software implementation
16       GNU roff, groff(1).  groff implements the look-and-feel and functional‐
17       ity of its ancestors, with many extensions.
18
19       The  ancestry  of  roff is described in section HISTORY.  In this docu‐
20       ment, the term roff always refers to the general  class  of  roff  pro‐
21       grams, not to the roff command provided in early UNIX systems.
22
23       In spite of its age, roff is in wide use today, for example, the manual
24       pages on UNIX systems (man pages), many software books, system documen‐
25       tation,  standards,  and  corporate documents are written in roff.  The
26       roff output for text devices is still unmatched, and its graphical out‐
27       put  has  the  same  quality as other free type-setting programs and is
28       better than some of the commercial systems.
29
30       roff is used to format UNIX manual pages, (or man pages), the  standard
31       documentation system on many UNIX-derived operating systems.
32
33       This document describes the history of the development of the roff sys‐
34       tem; some usage aspects common to all roff  versions,  details  on  the
35       roff pipeline, which is usually hidden behind front-ends like groff(1);
36       a general overview of the formatting language; some  tips  for  editing
37       roff files; and many pointers to further readings.
38

HISTORY

40       Document formatting by computer dates back to the 1960s.  The roff sys‐
41       tem itself is intimately connected to the Unix  operating  system,  but
42       its roots go back to the earlier operating systems CTSS and Multics.
43
44   The Predecessor RUNOFF
45       roff's ancestor RUNOFF was written in the MAD language by Jerry Saltzer
46       for the Compatible Time Sharing System (CTSS), a project of the  Massa‐
47       chusetts  Institute  of  Technology (MIT), in 1963 and 1964 – note that
48       CTSS commands were all uppercase.
49
50       In 1965, MIT's Project MAC  teamed  with  Bell  Telephone  Laboratories
51       (BTL)  and  General  Electric  to  begin  the  Multics  system ⟨http://
52       www.multicians.org⟩.  A command called runoff was written  for  Multics
53       in  the late 60s in the BCPL language, by Bob Morris, Doug McIlroy, and
54       other members of the Multics team.
55
56       Like its CTSS ancestor, Multics runoff formatted an input file consist‐
57       ing  of  text  and command lines; commands began with a period and were
58       two letters.  Output from these commands was to terminal  devices  such
59       as  IBM  Selectric  terminals.   Multics runoff had additional features
60       added, such as the ability to do two-pass  formatting;  it  became  the
61       main format for Multics documentation and text processing.
62
63       BCPL  and  runoff  were ported to the GCOS system at Bell Labs when BTL
64       left the development of Multics.
65
66   The Classical nroff/troff System
67       At BTL, there was a need to drive the Graphic Systems CAT typesetter, a
68       graphical output device from a PDP-11 computer running Unix.  As runoff
69       was too limited for this task it was further developed into a more pow‐
70       erful  text  formatting  system  by Joseph F. Ossanna, who already pro‐
71       grammed several runoff ports.
72
73       The name runoff was shortened to roff.  The greatly  enlarged  language
74       of  Ossanna's version already included all elements of a full roff sys‐
75       tem.  All modern roff systems try to implement  compatibility  to  this
76       system.  So Joe Ossanna can be called the father of all roff systems.
77
78       This first roff system had three formatter programs.
79
80       troff  (typesetter roff) generated a graphical output for the CAT type‐
81              setter as its only device.
82
83       nroff  produced text output suitable for terminals and line printers.
84
85       roff   was the reimplementation of the former runoff program  with  its
86              limited  features; this program was abandoned in later versions.
87              Today, the name roff is used to refer to a troff/nroff system as
88              a whole.
89
90       Ossanna's first version was written in the PDP-11 assembly language and
91       released in 1973.  Brian  Kernighan  joined  the  roff  development  by
92       rewriting it in the C programming language.  The C version was released
93       in 1975.
94
95       The syntax of the formatting language of the nroff/troff  programs  was
96       documented  in  the  famous  Troff User's Manual [CSTR #54], first pub‐
97       lished in 1976, with further revisions up to 1992 by  Brian  Kernighan.
98       This  document  is the specification of the classical troff.  All later
99       roff systems tried to establish compatibility with this specification.
100
101       After Ossanna's death in 1977, Kernighan went on with developing troff.
102       In the late 1970s, Kernighan equipped troff with a general interface to
103       support more devices, the intermediate output format, and the  postpro‐
104       cessor  system.  This completed the structure of a roff system as it is
105       still in use today; see section USING ROFF.  In 1979,  these  novelties
106       were  described in the paper [CSTR #97].  This new troff version is the
107       basis for all existing newer troff systems, including groff.   On  some
108       systems,  this device independent troff got a binary of its own, called
109       ditroff(7).  All modern troff programs already provide the full ditroff
110       capabilities automatically.
111
112   Availability
113       The  source  code  of both the ancient Unix and classical troff weren't
114       available for two decades.  Meanwhile, it is accessible again (on-line)
115       for non-commercial use, cf. section SEE ALSO.
116
117   Free roff
118       The  most  important  free  roff  project was the GNU implementation of
119       troff, written from scratch by James Clark and put under the GNU Public
120       License ⟨http://www.gnu.org/copyleft⟩.  It was called groff (GNU roff).
121       See groff(1) for an overview.
122
123       The groff system is still actively developed.  It is compatible to  the
124       classical  troff, but many extensions were added.  It is the first roff
125       system that is available on almost all operating systems –  and  it  is
126       free.  This makes groff the de-facto roff standard today.
127
128       An alternative is Gunnar Ritter's Heirloom Documentation Tools ⟨http://
129       heirloom.sf.net⟩ project, started in 2005, which provides enhanced ver‐
130       sions  of  the  various  roff tools found in the OpenSolaris and Plan 9
131       operating systems, now available under free licenses.
132

USING ROFF

134       Most people won't even notice that they are actually using roff.   When
135       you  read  a system manual page (man page) roff is working in the back‐
136       ground.  roff documents can be  viewed  with  a  native  viewer  called
137       xditview(1x),  a  standard  program  of  the X window distribution, see
138       X(7x).  But using roff explicitly isn't difficult either.
139
140       Some roff implementations provide wrapper programs that make it easy to
141       use  the  roff  system on the shell command line.  For example, the GNU
142       roff implementation groff(1) provides command line options to avoid the
143       long command pipes of classical troff; a program grog(1) tries to guess
144       from the document which arguments should be used for a  run  of  groff;
145       people  who  do not like specifying command line options should try the
146       groffer(1) program for  graphically  displaying  groff  files  and  man
147       pages.
148
149   The roff Pipe
150       Each  roff  system  consists of preprocessors, roff formatter programs,
151       and a set of device postprocessors.  This concept makes  heavy  use  of
152       the piping mechanism, that is, a series of programs is called one after
153       the other, where the output of each program in the queue  is  taken  as
154       the input for the next program.
155
156              cat file | ... | preproc | ... | troff options | postproc
157
158       The  preprocessors generate roff code that is fed into a roff formatter
159       (e.g. troff), which in turn generates intermediate output that  is  fed
160       into a device postprocessor program for printing or final output.
161
162       All  of  these  parts use programming languages of their own; each lan‐
163       guage is totally unrelated to the other parts.   Moreover,  roff  macro
164       packages that were tailored for special purposes can be included.
165
166       Most  roff  documents  use  the macros of some package, intermixed with
167       code for one or more preprocessors, spiced with some elements from  the
168       plain roff language.  The full power of the roff formatting language is
169       seldom needed by users; only programmers of macro packages need to know
170       about the gory details.
171
172   Preprocessors
173       A roff preprocessor is any program that generates output that syntacti‐
174       cally obeys the rules of the roff formatting language.  Each preproces‐
175       sor  defines  a  language  of its own that is translated into roff code
176       when run through the preprocessor program.  Parts written in these lan‐
177       guages  may  be included within a roff document; they are identified by
178       special roff requests or macros.  Each document  that  is  enhanced  by
179       preprocessor  code  must be run through all corresponding preprocessors
180       before it is fed into the actual roff formatter program, for  the  for‐
181       matter  just ignores all alien code.  The preprocessor programs extract
182       and transform only the document parts that are determined for them.
183
184       There are a lot of free and commercial  roff  preprocessors.   Some  of
185       them  aren't available on each system, but there is a small set of pre‐
186       processors that are considered as an integral part of each roff system.
187       The classical preprocessors are
188
189              tbl      for tables.
190              eqn      for mathematical formulæ.
191              pic      for drawing diagrams.
192              refer    for bibliographic references.
193              soelim   for including macro files from standard locations.
194              chem     for drawing chemical formulæ.
195
196       Other known preprocessors that are not available on all systems include
197
198              grap   for constructing graphical elements.
199              grn    for including gremlin(1) pictures.
200
201   Formatter Programs
202       A roff formatter is a program that parses documents written in the roff
203       formatting language or uses some of the roff macro packages.  It gener‐
204       ates  intermediate  output,  which  is intended to be fed into a single
205       device postprocessor that must be specified by a command-line option to
206       the  formatter  program.   The documents must have been run through all
207       necessary preprocessors before.
208
209       The output produced by a roff formatter is represented in  yet  another
210       language,  the  intermediate  output format or troff output.  This lan‐
211       guage was first specified in [CSTR #97]; its  GNU  extension  is  docu‐
212       mented  in groff_out(5).  The intermediate output language is a kind of
213       assembly language compared to the high-level roff language.  The gener‐
214       ated  intermediate  output  is  optimized for a special device, but the
215       language is the same for every device.
216
217       The roff formatter is the heart of the roff  system.   The  traditional
218       roff had two formatters, nroff for text devices and troff for graphical
219       devices.
220
221       Often, the name troff is used as a general term to refer to  both  for‐
222       matters.
223
224   Devices and Postprocessors
225       Devices are hardware interfaces like printers, text or graphical termi‐
226       nals, etc., or software interfaces such as a conversion into a  differ‐
227       ent text or graphical format.
228
229       A  roff  postprocessor is a program that transforms troff output into a
230       form suitable for a special device.  The roff postprocessors  are  like
231       device drivers for the output target.
232
233       For  each  device there is a postprocessor program that fits the device
234       optimally.  The postprocessor parses the generated intermediate  output
235       and generates device-specific code that is sent directly to the device.
236
237       The  names  of the devices and the postprocessor programs are not fixed
238       because they greatly depend on the software and hardware  abilities  of
239       the  actual  computer.  For example, the classical devices mentioned in
240       [CSTR #54] have greatly changed since the  classical  times.   The  old
241       hardware  doesn't  exist  any  longer and the old graphical conversions
242       were quite imprecise when compared to their modern counterparts.
243
244       For example, the Postscript device post in classical troff had a  reso‐
245       lution  of  720  units  per  inch, while groff's ps device has 72000, a
246       refinement of factor 100.
247
248       Today the operating systems provide device drivers  for  most  printer-
249       like  hardware, so it isn't necessary to write a special hardware post‐
250       processor for each printer.
251

ROFF PROGRAMMING

253       Documents using roff are normal text files decorated by roff formatting
254       elements.  The roff formatting language is quite powerful; it is almost
255       a full programming language and provides elements to enlarge  the  lan‐
256       guage.   With  these, it became possible to develop macro packages that
257       are tailored for special applications.  Such macro  packages  are  much
258       handier  than  plain  roff.  So most people will choose a macro package
259       without worrying about the internals of the roff language.
260
261   Macro Packages
262       Macro packages are collections of macros that are suitable to format  a
263       special  kind of documents in a convenient way.  This greatly eases the
264       usage of roff.  The macro definitions of a package are kept in  a  file
265       called name.tmac (classically tmac.name).  All tmac files are stored in
266       one or more directories at standardized positions.  Details on the nam‐
267       ing of macro packages and their placement is found in groff_tmac(5).
268
269       A  macro  package  that is to be used in a document can be announced to
270       the formatter by the command line option -m, see troff(1), or it can be
271       specified  within  a  document using the file inclusion requests of the
272       roff language, see groff(7).
273
274       Famous classical macro packages are man for traditional man pages, mdoc
275       for  BSD-style  manual  pages;  the macro sets for books, articles, and
276       letters are me (probably from the first name of its creator  Eric  All‐
277       man), ms (from Manuscript Macros), and mm (from Memorandum Macros).
278
279   The roff Formatting Language
280       The  classical  roff  formatting  language  is  documented in the Troff
281       User's Manual [CSTR #54].  The roff language is a full programming lan‐
282       guage  providing  requests,  definition  of  macros,  escape sequences,
283       string variables, number or size registers, and flow controls.
284
285       Requests are the predefined basic formatting commands  similar  to  the
286       commands  at  the  shell prompt.  The user can define request-like ele‐
287       ments using predefined roff elements.  These are then called macros.  A
288       document  writer  will not note any difference in usage for requests or
289       macros; both are written on a line on their own starting with a dot.
290
291       Escape sequences are roff elements starting with a backslash `\'.  They
292       can  be  inserted  anywhere, also in the midst of text in a line.  They
293       are used to implement various features, including the insertion of non-
294       ASCII  characters  with \(, font changes with \f, in-line comments with
295       \", the escaping of special control characters like \\, and many  other
296       features.
297
298       Strings  are  variables that can store a string.  A string is stored by
299       the .ds request.  The stored string can be retrieved later  by  the  \*
300       escape sequence.
301
302       Registers  store  numbers  and  sizes.   A register can be set with the
303       request .nr and its value can be retrieved by the escape sequence \n.
304

FILE NAME EXTENSIONS

306       Manual pages (man pages) take the section number as a file name  exten‐
307       sion,  e.g., the filename for this document is roff.7, i.e., it is kept
308       in section 7 of the man pages.
309
310       The classical macro packages take the package  name  as  an  extension,
311       e.g. file.me for a document using the me macro package, file.mm for mm,
312       file.ms for ms, file.pic for pic files, etc.
313
314       But there is no  general  naming  scheme  for  roff  documents,  though
315       file.tr  for  troff file is seen now and then.  Maybe there should be a
316       standardization for the filename extensions of roff files.
317
318       File name extensions can be very handy in conjunction with the  less(1)
319       pager.   It  provides the possibility to feed all input into a command-
320       line pipe that is specified in the shell environment variable LESSOPEN.
321       This process is not well documented, so here an example:
322
323              LESSOPEN='|lesspipe %s'
324
325       where lesspipe is either a system supplied command or a shell script of
326       your own.
327

EDITING ROFF

329       The best program for editing a roff document is Emacs (or Xemacs),  see
330       emacs(1).   It provides an nroff mode that is suitable for all kinds of
331       roff dialects.  This mode can be activated by the following methods.
332
333       When editing a file within Emacs the mode can be changed by typing `M-x
334       nroff-mode',  where  M-x  means  to hold down the Meta key (or Alt) and
335       hitting the x key at the same time.
336
337       But it is also possible to have the mode  automatically  selected  when
338       the file is loaded into the editor.
339
340       ·      The  most  general  method is to include the following 3 comment
341              lines at the end of the file.
342
343                     .\" Local Variables:
344                     .\" mode: nroff
345                     .\" End:
346
347       ·      There is a set of file name extensions, e.g. the man pages  that
348              trigger the automatic activation of the nroff mode.
349
350       ·      Theoretically, it is possible to write the sequence
351
352                     .\" -*- nroff -*-
353
354              as  the  first  line  of a file to have it started in nroff mode
355              when loaded.  Unfortunately, some applications such as  the  man
356              program are confused by this; so this is deprecated.
357
358       All  roff  formatters  provide automated line breaks and horizontal and
359       vertical spacing.  In order to not disturb this, the following tips can
360       be helpful.
361
362       ·      Never include empty or blank lines in a roff document.  Instead,
363              use the empty request (a line consisting of a  dot  only)  or  a
364              line comment .\" if a structuring element is needed.
365
366       ·      Never  start  a  line  with  whitespace because this can lead to
367              unexpected behavior.  Indented paragraphs can be constructed  in
368              a controlled way by roff requests.
369
370       ·      Start  each sentence on a line of its own, for the spacing after
371              a dot is handled differently depending on whether it  terminates
372              an  abbreviation or a sentence.  To distinguish both cases, do a
373              line break after each sentence.
374
375       ·      To additionally use the auto-fill mode in Emacs, it is  best  to
376              insert  an  empty roff request (a line consisting of a dot only)
377              after each sentence.
378
379       The following example shows how optimal roff editing could look.
380
381              This is an example for a
382              .I roff
383              document.
384              .
385              This is the next sentence in the same paragraph.
386              .
387              This is a longer sentence stretching over several
388              lines; abbreviations like `cf.' are easily
389              identified because the dot is not followed by a
390              line break.
391              .
392              In the output, this will still go to the same
393              paragraph.
394
395       Besides Emacs, some other editors provide nroff style files  too,  e.g.
396       vim(1), an extension of the vi(1) program.
397

SEE ALSO

399       There  is a lot of documentation on roff.  The original papers on clas‐
400       sical troff are still available, and all aspects  of  groff  are  docu‐
401       mented in great detail.
402
403   Internet sites
404       troff.org
405              The  historical  troff  site  ⟨http://www.troff.org⟩ provides an
406              overview and pointers to all historical aspects of roff.
407
408       Multics
409              The Multics site ⟨http://www.multicians.org⟩ contains a  lot  of
410              information  on  the  MIT  projects,  CTSS, Multics, early Unix,
411              including runoff; especially useful are a glossary and the  many
412              links to ancient documents.
413
414       Unix Archive
415              The  Ancient  Unixes Archive ⟨http://www.tuhs.org/Archive/⟩ pro‐
416              vides the source code and some binaries of  the  ancient  Unixes
417              (including  the source code of troff and its documentation) that
418              were made public by Caldera since 2001, e.g. of the famous  Unix
419              version  7  for PDP-11 at the Unix V7 site ⟨http://www.tuhs.org/
420              Archive/PDP-11/Trees/V7⟩.
421
422       Developers at AT&T Bell Labs
423              Bell Labs Computing and Mathematical Sciences Research  ⟨http://
424              www.bell-labs.com/⟩  provides  a  search  facility  for tracking
425              information on the early developers.
426
427       Plan 9 The Plan 9 operating system ⟨http://plan9.bell-labs.com⟩ by AT&T
428              Bell Labs.
429
430       runoff Jerry   Saltzer's   home  page  ⟨http://web.mit.edu/Saltzer/www/
431              publications/pubs.html⟩ stores some documents using the  ancient
432              RUNOFF formatting language.
433
434       CSTR Papers
435              The   Bell   Labs   CSTR   site  ⟨http://cm.bell-labs.com/cm/cs/
436              cstr.html⟩ stores the original troff  manuals  (CSTR  #54,  #97,
437              #114,  #116,  #122)  and famous historical documents on program‐
438              ming.
439
440       GNU roff
441              The groff web site ⟨http://www.gnu.org/software/groff⟩  provides
442              the free roff implementation groff, the actual standard roff.
443
444   Historical roff Documentation
445       Many  classical  troff  documents are still available on-line.  The two
446       main manuals of the troff language are
447
448       [CSTR #54]
449              J.  F.  Ossanna,  Nroff/Troff  User's  Manualhttp://cm.bell-
450              labs.com/cm/cs/cstr/54.ps.gz⟩; Bell Labs, 1976; revised by Brian
451              Kernighan, 1992.
452
453       [CSTR #97]
454              Brian Kernighan, A Typesetter-independent TROFFhttp://cm.bell-
455              labs.com/cm/cs/cstr/97.ps.gz⟩,  Bell  Labs,  1981, revised March
456              1982.
457
458       The “little language” roff papers are
459
460       [CSTR #114]
461              Jon L. Bentley and Brian W. Kernighan, GRAP    A  Language  for
462              Typesetting      Graphshttp://cm.bell-labs.com/cm/cs/cstr/
463              114.ps.gz⟩; Bell Labs, August 1984.
464
465       [CSTR #116]
466              Brian W. Kernighan, PIC  A Graphics  Language  for  Typesetting
467http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz⟩;    Bell    Labs,
468              December 1984.
469
470       [CSTR #122]
471              J. L. Bentley, L. W. Jelinski, and B. W.  Kernighan,  CHEM    A
472              Program  for  Typesetting Chemical Structure Diagrams, Computers
473              and  Chemistryhttp://cm.bell-labs.com/cm/cs/cstr/122.ps.gz⟩;
474              Bell Labs, April 1986.
475
476   Manual Pages
477       Due  to  its  complex structure, a full roff system has many man pages,
478       each describing a single aspect of roff.  Unfortunately,  there  is  no
479       general  naming  scheme  for the documentation among the different roff
480       implementations.
481
482       In groff, the man page groff(1) contains a survey of all  documentation
483       available in groff.
484
485       On  other  systems,  you  are on your own, but troff(1) might be a good
486       starting point.
487

AUTHORS

489       Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free
490       Software Foundation, Inc.
491
492       This document is distributed under the terms of the FDL (GNU Free Docu‐
493       mentation License) version 1.3 or later.  You should  have  received  a
494       copy of the FDL on your system, it is also available on-line at the GNU
495       copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩.
496
497       This document is part of groff, the  GNU  roff  distribution.   It  was
498       written  by  Bernd  Warken  ⟨groff-bernd.warken-72@web.de⟩; it is main‐
499       tained by Werner Lemberg ⟨wl@gnu.org⟩.
500
501
502
503Groff Version 1.22.2            7 February 2013                        ROFF(7)
Impressum