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 type-setting programs, known
10       under names like troff, nroff, ditroff, groff, etc.  A  roff  type-set‐
11       ting  system  consists  of an extensible text formatting language and a
12       set of programs for printing and  converting  to  other  text  formats.
13       Traditionally,  it  is  the  main text processing system of Unix; every
14       Unix-like operating system still distributes a roff system  as  a  core
15       package.
16
17       The  most  common roff system today is the free software implementation
18       GNU roff, groff(1).  The pre-groff implementations are referred  to  as
19       classical  (dating  back  as long as 1973).  groff implements the look-
20       and-feel and functionality of its classical  ancestors,  but  has  many
21       extensions.   As  groff  is  the only roff system that is available for
22       every (or almost every) computer system it is the de-facto  roff  stan‐
23       dard today.
24
25       In  some  ancient  Unix  systems,  there  was a binary called roff that
26       implemented the even more ancient runoff of the Multics operating  sys‐
27       tem,  cf.  section HISTORY.  The functionality of this program was very
28       restricted even in comparison to ancient troff; it is not supported any
29       longer.  Consequently, in this document, the term roff always refers to
30       the general meaning of roff system, not to the ancient roff binary.
31
32       In spite of its age, roff is in wide use today, for example, the manual
33       pages on UNIX systems (man pages), many software books, system documen‐
34       tation, standards, and corporate documents are written  in  roff.   The
35       roff output for text devices is still unmatched, and its graphical out‐
36       put has the same quality as other free  type-setting  programs  and  is
37       better than some of the commercial systems.
38
39       The  most popular application of roff is the concept of manual pages or
40       shortly man pages; this is the standard documentation  system  on  many
41       operating systems.
42
43       This  document describes the historical facts around the development of
44       the roff system; some  usage  aspects  common  to  all  roff  versions,
45       details on the roff pipeline, which is usually hidden behind front-ends
46       like groff(1); an general overview of  the  formatting  language;  some
47       tips for editing roff files; and many pointers to further readings.
48

HISTORY

50       The roff text processing system has a very long history, dating back to
51       the 1960s.  The roff system itself is intimately connected to the  Unix
52       operating  system,  but its roots go back to the earlier operating sys‐
53       tems CTSS and Multics.
54
55   The Predecessor runoff
56       The evolution of roff is intimately related to the history of the oper‐
57       ating  systems.  Its predecessor runoff was written by Jerry Saltzer on
58       the CTSS operating system (Compatible Time Sharing System) as early  as
59       1961.  When CTTS was further developed into the operating system Mul‐
60       tics ⟨http://www.multicians.org⟩, the famous predecessor of  Unix  from
61       1963, runoff became the main format for documentation and text process‐
62       ing.  Both operating systems could only be run on very  expensive  com‐
63       puters at that time, so they were mostly used in research and for offi‐
64       cial and military tasks.
65
66       The possibilities of the runoff language were quite limited as compared
67       to  modern  roff.   Only  text  output was possible in the 1960s.  This
68       could be implemented by a set of requests of length 2,  many  of  which
69       are  still identically used in roff.  The language was modelled accord‐
70       ing to the habits of typesetting in the pre-computer age,  where  lines
71       starting  with  a  dot  were  used  in manuscripts to denote formatting
72       requests to the person who would perform the typesetting manually later
73       on.
74
75       The  runoff program was written in the PL/1 language first, later on in
76       BCPL, the grandmother of the C programming language.   In  the  Multics
77       operating  system,  the  help  system was handled by runoff, similar to
78       roff's task to manage the Unix manual pages.  There are still documents
79       written  in  the runoff language; for examples see Saltzer's home page,
80       cf. section SEE ALSO.
81
82   The Classical nroff/troff System
83       In the 1970s, the Multics off-spring Unix became more and more  popular
84       because it could be run on affordable machines and was easily available
85       for universities at that time.  At MIT (the Massachusetts Institute  of
86       Technology),  there  was  a  need to drive the Wang Graphic Systems CAT
87       typesetter, a graphical output device from a  PDP-11  computer  running
88       Unix.  As runoff was too limited for this task it was further developed
89       into a more powerful text formatting system by Josef F. Osanna, a  main
90       developer  of  the  Multics  operating system and programmer of several
91       runoff ports.
92
93       The name runoff was shortened to roff.  The greatly  enlarged  language
94       of  Osanna's  concept included already all elements of a full roff sys‐
95       tem.  All modern roff systems try to implement  compatibility  to  this
96       system.  So Joe Osanna can be called the father of all roff systems.
97
98       This first roff system had three formatter programs.
99
100       troff  (typesetter roff) generated a graphical output for the CAT type‐
101              setter as its only device.
102
103       nroff  produced text output suitable for terminals and line printers.
104
105       roff   was the reimplementation of the former runoff program  with  its
106              limited  features; this program was abandoned in later versions.
107              Today, the name roff is used to refer to a troff/nroff sytem  as
108              a whole.
109
110       Osanna  first  version  was written in the PDP-11 assembly language and
111       released in 1973.  Brian  Kernighan  joined  the  roff  development  by
112       rewriting it in the C programming language.  The C version was released
113       in 1975.
114
115       The syntax of the formatting language of the nroff/troff  programs  was
116       documented  in  the  famous  Troff User's Manual [CSTR #54], first pub‐
117       lished in 1976, with further revisions up to 1992 by  Brian  Kernighan.
118       This  document  is the specification of the classical troff.  All later
119       roff systems tried to establish compatibility with this specification.
120
121       After Osanna had died in 1977 by a heart-attack at the age of about 50,
122       Kernighan  went  on  with  developing troff.  The next milestone was to
123       equip troff with a general  interface  to  support  more  devices,  the
124       intermediate  output  format  and  the postprocessor system.  This com‐
125       pleted the structure of a roff system as it is still in use today;  see
126       section  USING  ROFF.   In  1979, these novelties were described in the
127       paper [CSTR #97].  This new troff version is the basis for all existing
128       newer  troff  systems,  including  groff.  On some systems, this device
129       independent troff got a binary of its own, called ditroff(7).  All mod‐
130       ern  troff programs already provide the full ditroff capabilities auto‐
131       matically.
132
133   Commercialization
134       A major degradation occurred when the easily available Unix 7 operating
135       system  was  commercialized.  A whole bunch of divergent operating sys‐
136       tems emerged, fighting  each  other  with  incompatibilities  in  their
137       extensions.   Luckily, the incompatibilities did not fight the original
138       troff.  All of the different commercial roff systems made heavy use  of
139       Osanna/Kernighan's open source code and documentation, but sold them as
140       “their” system — with only minor additions.
141
142       The source code of both the ancient Unix and  classical  troff  weren't
143       available  for  two  decades.   Fortunately, Caldera bought SCO UNIX in
144       2001.  In the following, Caldera made the ancient source code  accessi‐
145       ble on-line for non-commercial use, cf. section SEE ALSO.
146
147   Free roff
148       None  of  the commercial roff systems could attain the status of a suc‐
149       cessor for the general roff development.  Everyone was only  interested
150       in their own stuff.  This led to a steep downfall of the once excellent
151       Unix operating system during the 1980s.
152
153       As a counter-measure to the galopping commercialization, AT&T Bell Labs
154       tried  to  launch  a rescue project with their Plan 9 operating system.
155       It is freely available for non-commercial use, even  the  source  code,
156       but  has a proprietary license that empedes the free development.  This
157       concept is outdated, so Plan 9 was not accepted as a platform to bundle
158       the main-stream development.
159
160       The only remedy came from the emerging free operatings systems (386BSD,
161       GNU/Linux, etc.) and software projects  during  the  1980s  and  1990s.
162       These  implemented  the ancient Unix features and many extensions, such
163       that the old experience is not lost.  In the  21st  century,  Unix-like
164       systems  are again a major factor in computer industry — thanks to free
165       software.
166
167       The most important free roff project was the GNU port of troff, created
168       by James Clark and put under the GNU Public License ⟨http://
169       www.gnu.org/copyleft⟩.  It was called groff (GNU roff).   See  groff(1)
170       for an overview.
171
172       The  groff system is still actively developed.  It is compatible to the
173       classical troff, but many extensions were added.  It is the first  roff
174       system  that  is  available on almost all operating systems — and it is
175       free.  This makes groff the de-facto roff standard today.
176

USING ROFF

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

ROFF PROGRAMMING

298       Documents using roff are normal text files decorated by roff formatting
299       elements.  The roff formatting language is quite powerful; it is almost
300       a full programming language and provides elements to enlarge  the  lan‐
301       guage.   With  these, it became possible to develop macro packages that
302       are tailored for special applications.  Such macro  packages  are  much
303       handier  than  plain  roff.  So most people will choose a macro package
304       without worrying about the internals of the roff language.
305
306   Macro Packages
307       Macro packages are collections of macros that are suitable to format  a
308       special  kind of documents in a convenient way.  This greatly eases the
309       usage of roff.  The macro definitions of a package are kept in  a  file
310       called name.tmac (classically tmac.name).  All tmac files are stored in
311       one or more directories at standardized positions.  Details on the nam‐
312       ing of macro packages and their placement is found in groff_tmac(5).
313
314       A  macro  package  that is to be used in a document can be announced to
315       the formatter by the command line option -m, see troff(1), or it can be
316       specified  within  a  document using the file inclusion requests of the
317       roff language, see groff(7).
318
319       Famous classical macro packages are man for traditional man pages, mdoc
320       for  BSD-style  manual  pages;  the macro sets for books, articles, and
321       letters are me (probably from the first name of its creator  Eric  All‐
322       man), ms (from Manuscript Macros), and mm (from Memorandum Macros).
323
324   The roff Formatting Language
325       The  classical  roff formatting language is documented in the Troff Us‐
326       er's Manual [CSTR #54].  The roff language is a full  programming  lan‐
327       guage  providing  requests,  definition  of  macros,  escape sequences,
328       string variables, number or size registers, and flow controls.
329
330       Requests are the predefined basic formatting commands  similar  to  the
331       commands  at  the  shell prompt.  The user can define request-like ele‐
332       ments using predefined roff elements.  These are then called macros.  A
333       document  writer  will not note any difference in usage for requests or
334       macros; both are written on a line on their own starting with a dot.
335
336       Escape sequences are roff elements starting with a backslash `\'.  They
337       can  be  inserted  anywhere, also in the midst of text in a line.  They
338       are used to implement various features, including the insertion of non-
339       ASCII  characters  with \(, font changes with \f, in-line comments with
340       \", the escaping of special control characters like \\, and many  other
341       features.
342
343       Strings  are  variables that can store a string.  A string is stored by
344       the .ds request.  The stored string can be retrieved later  by  the  \*
345       escape sequence.
346
347       Registers  store numbers and sizes.  A register can be set with the re‐
348       quest .nr and its value can be retrieved by the escape sequence \n.
349

FILE NAME EXTENSIONS

351       Manual pages (man pages) take the section number as a file name  exten‐
352       sion,  e.g., the filename for this document is roff.7, i.e., it is kept
353       in section 7 of the man pages.
354
355       The classical macro packages take the package  name  as  an  extension,
356       e.g.   file.me  for  a document using the me macro package, file.mm for
357       mm, file.ms for ms, file.pic for pic files, etc.
358
359       But there is no  general  naming  scheme  for  roff  documents,  though
360       file.tr  for  troff file is seen now and then.  Maybe there should be a
361       standardization for the filename extensions of roff files.
362
363       File name extensions can be very handy in conjunction with the  less(1)
364       pager.   It  provides the possibility to feed all input into a command-
365       line pipe that is specified in the shell environment variable LESSOPEN.
366       This process is not well documented, so here an example:
367
368       sh# LESSOPEN='|lesspipe %s'
369
370       where lesspipe is either a system supplied command or a shell script of
371       your own.
372

EDITING ROFF

374       The best program for editing a roff document is Emacs (or Xemacs),  see
375       emacs(1).   It provides an nroff mode that is suitable for all kinds of
376       roff dialects.  This mode can be activated by the following methods.
377
378       When editing a file within Emacs the mode can be changed by typing `M-x
379       nroff-mode',  where  M-x  means  to hold down the Meta key (or Alt) and
380       hitting the x key at the same time.
381
382       But it is also possible to have the mode  automatically  selected  when
383       the file is loaded into the editor.
384
385       · The  most  general method is to include the following 3 comment lines
386         at the end of the file.
387
388         .\" Local Variables:
389         .\" mode: nroff
390         .\" End:
391
392       · There is a set of file name extensions, e.g. the man pages that trig‐
393         ger the automatic activation of the nroff mode.
394
395       · Theoretically, it is possible to write the sequence
396
397         .\" -*- nroff -*-
398
399         as  the  first  line  of a file to have it started in nroff mode when
400         loaded.  Unfortunately, some applications such as the man program are
401         confused by this; so this is deprecated.
402
403       All  roff  formatters  provide automated line breaks and horizontal and
404       vertical spacing.  In order to not disturb this, the following tips can
405       be helpful.
406
407       · Never  include empty or blank lines in a roff document.  Instead, use
408         the empty request (a line consisting of a dot only) or a line comment
409         .\" if a structuring element is needed.
410
411       · Never start a line with whitespace because this can lead to unexpect‐
412         ed behavior.  Indented paragraphs can be constructed in a  controlled
413         way by roff requests.
414
415       · Start each sentence on a line of its own, for the spacing after a dot
416         is handled differently depending on whether it terminates an abbrevi‐
417         ation  or a sentence.  To distinguish both cases, do a line break af‐
418         ter each sentence.
419
420       · To additionally use the auto-fill mode in Emacs, it is best to insert
421         an  empty  roff  request (a line consisting of a dot only) after each
422         sentence.
423
424       The following example shows how optimal roff editing could look.
425
426              This is an example for a roff document.
427              .
428              This is the next sentence in the same paragraph.
429              .
430              This is a longer sentence stretching over several
431              lines; abbreviations like `cf.' are easily
432              identified because the dot is not followed by a
433              line break.
434              .
435              In the output, this will still go to the same
436              paragraph.
437
438       Besides Emacs, some other editors provide nroff style files  too,  e.g.
439       vim(1), an extension of the vi(1) program.
440

BUGS

442       UNIX® is a registered trademark of the Open Group.  But things have im‐
443       proved considerably after Caldera had bought SCO UNIX in 2001.
444

SEE ALSO

446       There is a lot of documentation on roff.  The original papers on  clas‐
447       sical troff are still available, and all aspects of groff are document‐
448       ed in great detail.
449
450   Internet sites
451       troff.org
452              The historical troff  site  ⟨http://www.troff.org⟩  provides  an
453              overview  and  pointers to all historical aspects of roff.  This
454              web site is under construction;  once,  it  will  be  the  major
455              source for roff history.
456
457       Multics
458              The  Multics  site ⟨http://www.multicians.org⟩ contains a lot of
459              information on the MIT projects, CTSS, Multics, early Unix,  in‐
460              cluding  runoff;  especially  useful are a glossary and the many
461              links to ancient documents.
462
463       Unix Archive
464              The Ancient Unixes Archive  ⟨http://www.tuhs.org/Archive/⟩  pro‐
465              vides  the  source  code and some binaries of the ancient Unixes
466              (including the source code of troff and its documentation)  that
467              were  made public by Caldera since 2001, e.g. of the famous Unix
468              version 7 for PDP-11 at the Unix V7 site ⟨http://www.tuhs.org/
469              Archive/PDP-11/Trees/V7⟩.
470
471       Developers at AT&T Bell Labs
472              Bell Labs Computing and Mathematical Sciences Research ⟨http://
473              cm.bell-labs.com/cm/index.html⟩ provides a search  facility  for
474              tracking information on the early developers.
475
476       Plan 9 The Plan 9 operating system ⟨http://plan9.bell-labs.com⟩ by AT&T
477              Bell Labs.
478
479       runoff Jerry Saltzer's home page ⟨http://web.mit.edu/Saltzer/www/
480              publications/pubs.html⟩  stores some documents using the ancient
481              runoff formatting language.
482
483       CSTR Papers
484              The Bell Labs CSTR site ⟨http://cm.bell-labs.com/cm/cs/
485              cstr.html⟩  stores  the  original  troff manuals (CSTR #54, #97,
486              #114, #116, #122) and famous historical  documents  on  program‐
487              ming.
488
489       GNU roff
490              The  groff web site ⟨http://www.gnu.org/software/groff⟩ provides
491              the free roff implementation groff, the actual standard roff.
492
493   Historical roff Documentation
494       Many classical documents are still available  on-line.   The  two  main
495       manuals of the troff language are
496
497       [CSTR #54]
498              J. F. Osanna, Nroff/Troff User's Manual ⟨http://
499              cm.bell-labs.com/cm/cs/54.ps⟩; Bell Labs, 1976; revised by Brian
500              Kernighan, 1992.
501
502
503       [CSTR #97]
504              Brian Kernighan, A Typesetter-independent TROFF ⟨http://
505              cm.bell-labs.com/cm/cs/97.ps⟩, Bell Labs,  1981,  revised  March
506              1982.
507
508       The "little language" roff papers are
509
510       [CSTR #114]
511              Jon L. Bentley and Brian W. Kernighan, GRAP  A Language for
512              Typesetting Graphshttp://cm.bell-labs.com/cm/cs/114.ps⟩;  Bell
513              Labs, August 1984.
514
515       [CSTR #116]
516              Brian W. Kernighan, PIC -- A Graphics Language for Typesetting
517http://cm.bell-labs.com/cm/cs/116.ps⟩;  Bell   Labs,   December
518              1984.
519
520       [CSTR #122]
521              J. L. Bentley, L. W. Jelinski, and B. W. Kernighan, CHEM  A
522              Program for Typesetting Chemical Structure Diagrams, Computers
523              and Chemistryhttp://cm.bell-labs.com/cm/cs/122.ps⟩; Bell Labs,
524              April 1986.
525
526   Manual Pages
527       Due to its complex structure, a full roff system has  many  man  pages,
528       each  describing  a  single aspect of roff.  Unfortunately, there is no
529       general naming scheme for the documentation among  the  different  roff
530       implementations.
531
532       In  groff, the man page groff(1) contains a survey of all documentation
533       available in groff.
534
535       On other systems, you are on your own, but troff(1)  might  be  a  good
536       starting point.
537

AUTHORS

539       Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
540
541       This document is distributed under the terms of the FDL (GNU Free Docu‐
542       mentation License) version 1.1 or later.  You should  have  received  a
543       copy of the FDL on your system, it is also available on-line at the GNU
544       copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩.
545
546       This document is part of groff, the  GNU  roff  distribution.   It  was
547       written  by  Bernd Warken ⟨bwarken@mayn.de⟩; it is maintained by Werner
548       Lemberg ⟨wl@gnu.org⟩.
549
550
551
552Groff Version 1.18.1.4           23 April 2002                         ROFF(7)
Impressum