5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000 Free Software Foundation, Inc.
8 written by Bernd Warken <bwarken@mayn.de>
10 Last update: 17 May 2000
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.1 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being this .ig-section and AUTHOR, with no
16 Front-Cover Texts, and with no Back-Cover Texts.
18 A copy of the Free Documentation License is included as a file called
19 FDL in the main directory of the groff source package.
22 .\" --------------------------------------------------------------------
24 .\" --------------------------------------------------------------------
33 .\" text lines in macro definitions or bracketed sections \{...\}
42 . ds @tmp@ \fB\\$1\fP\fI\\$2\fP
44 . text \\*[@tmp@]\fR\\$*\fP
50 . ds @tmp@ \f(CB\\$1\fP
57 . ds @tmp@ `\f(CB\\$1\fP'
64 . ds @tmp@ \f(CB\e\\$1\fP
71 . ds @tmp@ \f(CI\\$1\fP
78 . ds @tmp@ \&\\$1\ \f(CR\\$2\fP
84 .\" --------------------------------------------------------------------
86 .\" --------------------------------------------------------------------
87 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
89 roff \- a survey of the roff typesetting system
90 .\" --------------------------------------------------------------------
92 .\" --------------------------------------------------------------------
94 is the general name for a set of type-setting programs, known under
101 The roff type-setting system consists of a formatting language, macro
102 packages, preprocessors, postprocessors for output devices, user
103 front-end programs, and conversion tools.
105 The most common roff system today is the free software implementation
108 The pre-groff implementations are referred to as `classical' (dating
109 back as long as 1973).
112 is backward-compatible to its classical ancestors, but has many
113 extensions, and is still evolving.
114 As it is available for almost every computer system it is the de-facto
117 In spite of its age, roff is in wide use today, e.g., the manual pages
121 The roff output for text devices is still unmatched, and its graphical
122 output has the same quality as the other free type-setting programs and
123 is better than some of the commercial systems.
125 This document gives only an overview and provides pointers to further
128 This document is not maintained and might be out of date. For the real
129 documentation refer to the groff info file that contains the detailed,
130 actual and concise reference information.
131 .\" --------------------------------------------------------------------
132 .SH "FORMATTING LANGUAGE"
133 .\" --------------------------------------------------------------------
134 There are three terms that refer to the language of the
139 is used when the classical aspects of
141 are stressed, the term
143 includes the GNU extensions, whereas
147 The main source of documentation for all aspects of the
149 is the groff info file. The manual page
150 .BR groff (@MAN7EXT@)
151 gives a short description of all predefined language elements.
153 Documents using roff are normal text files decorated by formatting
155 It is very easy to write high-quality documents by using one of the
157 These are like high-level programming languages, while the bare roff
158 language compares to a low-level language like C or assembler.
160 The roff language is a full programming language providing low-level
161 requests, definition of macros, escape sequences, string variables,
162 number or size registers, and C-like flow controls.
164 In the 1980s, it was even possible to write the common utilities for
165 system administration by only using troff.
166 There were contests on writing the most unreadable program fake by
167 exclusively using troff.
168 Because of security impacts, these dangerous features were removed in
172 Some clarification on the language elements seems to be wanted.
173 Requests are basic formatting commands defined by programming languages
174 like C, C++, etc., whereas macros are formatting commands that are
175 written in the roff language.
176 A document writer will not note any difference in usage for requests or
177 macros, both are written on a line on their own starting with a dot
179 But the user may define her own macros if desired.
181 Escape sequences are in-line elements starting with a backslash
183 They are used to implement various features, including the insertion of
184 non-ASCII characters with
186 the content of strings with
188 and register variables with
192 in-line comments with
194 the escaping of special control characters like
196 and many other features.
197 .\" --------------------------------------------------------------------
199 .\" --------------------------------------------------------------------
200 Formatters are the front-end programs that analyze a groff document and
201 translate it into a form that is suitable for a special device.
208 for graphical devices.
210 These programs still exist in the
212 implementation, but usually they are accessed through a program called
214 This combined and extended the old functionality into a single program.
215 It has many command-line options, most of them herited from
217 To ease the option jungle, the user-friendly utility
219 (from `groff guess') was created.
220 It tries to guess from the document which arguments should be used and
221 displays a suitable command line.
222 Though not being perfect, it is a good starting point.
223 .\" --------------------------------------------------------------------
225 .\" --------------------------------------------------------------------
226 The classical preprocessors that are still available in groff.
232 for including mathematical equations.
235 for constructing graphical elements (this preprocessor doesn't come with
236 groff; it is an extra package).
239 for including gremlin pictures.
242 for creating diagrams.
245 for bibliographic references.
248 for including other roff files.
251 for rectangular tables.
255 Each of these preprocessors defines its own language that is translated
256 into roff code when run through the preprocessor program.
257 So parts written in these languages may be included within a roff
259 Such an enhanced document is run through one or more corresponding
260 preprocessors before it is fed into the actual formatter.
262 The preprocessor programs extract and transform the document parts
264 They can be called either in a UNIX pipeline with their program name or
265 automatically with a groff option.
268 center, box, tab (@);
271 preprocessor@groff option
283 .\" --------------------------------------------------------------------
285 .\" --------------------------------------------------------------------
286 Macro packages are collections of macros that are suitable to format a
287 special kind of documents in a convenient way.
288 This greatly eases the usage of roff.
289 The macro definitions of a package are kept in a file called
293 is the internal roff name for this package.
294 All tmac files are stored in a single or few directories at standard
297 A macro package that is used in a document is specified by the command line
300 for the formatter like
306 General details on the naming of macro packages and their placement is
308 .BR tmac (@MAN5EXT@).
310 Famous classical macro packages are
320 for books, articles, and letters.
321 Besides these collections, groff provides an increasing number of new
322 macro packages for various applications, for example integration of or
323 conversion into other file formats.
324 .\" --------------------------------------------------------------------
325 .SH "FILE NAME EXTENSIONS"
326 .\" --------------------------------------------------------------------
327 Manual pages (man-pages) take the section number as a file name
328 extension, e.g., the filename for this document is
331 .prefixednumber section 7
334 The classical macro packages take the package name as an extension, e.g.
336 for a document using the
352 But there is no general naming scheme for roff documents, though
356 seems to be a good choice.
358 File name extensions can be very handy in conjunction with the
361 It provides the possibility to feed all input into a command-line pipe that
362 is specified in the shell environment variable
364 This process is not well documented, so here an example
365 .B LESSOPEN='|lesspipe %s'
368 is either a system supplied command or a shell script of your own.
370 .\" --------------------------------------------------------------------
372 .\" --------------------------------------------------------------------
373 Most text editors provide support for editing documents using roff.
374 Especially useful is the
376 in all flavors of the Emacs editor.
377 .\" --------------------------------------------------------------------
379 .\" --------------------------------------------------------------------
383 A colon separated list of directories in which to search for
385 .BR tmac (@MAN5EXT@).
393 A colon separated list of directories in which to search for the
397 will search in directories given in the
399 option before these, and in standard directories
400 .RB ( .:/usr/local/share/groff/font:/usr/lib/font )
402 .\" --------------------------------------------------------------------
404 .\" --------------------------------------------------------------------
407 installs all of its library files in a directory tree under
408 .IR /usr/local/share/groff .
409 This location might vary for different systems.
410 In the following, this directory is referred to as
414 .IB <groff_dir> /tmac/troffrc
415 Initialization file for troff.
417 .IB <groff_dir> /tmac/tmac. name
420 .IB <groff_dir> /font/dev name /DESC
421 Device description file for device
424 .IB <groff_dir> /font/dev name / F
429 .\" --------------------------------------------------------------------
431 .\" --------------------------------------------------------------------
432 The groff documentation is in evolution at the moment.
433 It is possible that small inconsistencies between different documents exist
435 .\" --------------------------------------------------------------------
437 .\" --------------------------------------------------------------------
438 This document is part of groff, the GNU roff distribution. It was
439 written by Bernd Warken <bwarken@mayn.de>.
441 It is distributed under the terms of the FDL (GNU Free Documentation
442 License) version 1.1 or later. You should have received a copy of the
443 FDL on your system, it is also available on-line under
446 .IR <http://www.gnu.org/copyleft/fdl.html> .
448 .\" --------------------------------------------------------------------
450 .\" --------------------------------------------------------------------
451 The main source of information is the
456 The predefined elements of the
458 language are also documented in the manual page
459 .BR groff (@MAN7EXT@).
461 Formatters and their wrappers:
462 .BR groff (@MAN1EXT@),
463 .BR grog (@MAN1EXT@),
464 .BR nroff (@MAN1EXT@),
466 .BR troff (@MAN1EXT@).
468 Postprocessors for the output devices:
469 .BR grodvi (@MAN1EXT@),
470 .BR grohtml (@MAN1EXT@),
471 .BR grolbp (@MAN1EXT@),
472 .BR grolj4 (@MAN1EXT@),
473 .BR grops (@MAN1EXT@),
475 .BR grotty (@MAN1EXT@).
477 Standard preprocessors:
482 .BR refer (@MAN1EXT@),
483 .BR soelim (@MAN1EXT@),
487 The man pages for macro packages include
488 .BR groff_tmac (@MAN5EXT@),
489 .BR groff_man (@MAN7EXT@),
490 .BR groff_markup (@MAN7EXT@),
491 .BR groff_mdoc (@MAN7EXT@),
492 .BR groff_mdoc.samples (@MAN7EXT@),
493 .BR groff_me (@MAN7EXT@),
494 .BR groff_mm (@MAN7EXT@),
495 .BR groff_mmroff (@MAN7EXT@),
496 .BR groff_ms (@MAN7EXT@),
498 .BR groff_msafer (@MAN7EXT@).
500 The following utilities are available:
501 .BR addftinfo (@MAN1EXT@),
502 .BR afmtodif (@MAN1EXT@),
503 .BR hpftodit (@MAN1EXT@),
504 .BR indxbib (@MAN1EXT@),
505 .BR lookbib (@MAN1EXT@),
506 .BR pfbtops (@MAN1EXT@),
507 .BR tfmtodit (@MAN1EXT@),
509 .BR gxditview (@MAN1EXT@).
511 For details on the GNU implementation of the
514 .BR groff_char (@MAN7EXT@),
515 .BR groff_font (@MAN7EXT@),
516 .BR groff_out (@MAN7EXT@),
519 in the main directory of the groff source distribution.
520 These also give details on how to contact or join the
526 documents are still available on-line.
527 Especially informative are the original Bell Labs proceedings for the old,
529 .I http://cm.bell-labs.com/cm/cs/cstr.html
530 and the collection of the late Richard S. Stevens at
531 .IR http://www.kohala.com/start/troff/ .