5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000, 2001 Free Software Foundation, Inc.
8 written by Bernd Warken <bwarken@mayn.de>
10 Permission is granted to copy, distribute and/or modify this document
11 under the terms of the GNU Free Documentation License, Version 1.1 or
12 any later version published by the Free Software Foundation; with the
13 Invariant Sections being this .ig-section and AUTHOR, with no
14 Front-Cover Texts, and with no Back-Cover Texts.
16 A copy of the Free Documentation License is included as a file called
17 FDL in the main directory of the groff source package.
20 .\" --------------------------------------------------------------------
22 .\" --------------------------------------------------------------------
31 .\" text lines in macro definitions or bracketed sections \{...\}
37 . ds @tmp@ \f(CB\\$1\fP
44 . ds @tmp@ `\f(CB\\$1\fP'
51 . ds @tmp@ \f(CB\e\\$1\fP
58 . ds @tmp@ \f(CI\\$1\fP
65 . ds @tmp@ \&\\$1\ \f(CR\\$2\fP
77 .\" --------------------------------------------------------------------
79 .\" --------------------------------------------------------------------
80 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
82 roff \- a survey of the roff typesetting system
83 .\" --------------------------------------------------------------------
85 .\" --------------------------------------------------------------------
87 is the general name for a set of type-setting programs, known under
94 The roff type-setting system consists of a formatting language, macro
95 packages, preprocessors, postprocessors for output devices, user
96 front-end programs, and conversion tools.
98 The most common roff system today is the free software implementation
101 The pre-groff implementations are referred to as `classical' (dating
102 back as long as 1973).
105 is backward-compatible to its classical ancestors, but has many
106 extensions, and is still evolving.
107 As it is available for almost every computer system it is the de-facto
110 In spite of its age, roff is in wide use today, e.g., the manual pages
114 The roff output for text devices is still unmatched, and its graphical
115 output has the same quality as the other free type-setting programs and
116 is better than some of the commercial systems.
118 This document gives only an overview and provides pointers to further
121 This document is not maintained and might be out of date. For the real
122 documentation refer to the groff info file that contains the detailed,
123 actual and concise reference information.
124 .\" --------------------------------------------------------------------
125 .SH "FORMATTING LANGUAGE"
126 .\" --------------------------------------------------------------------
127 There are three terms that refer to the language of the
132 is used when the classical aspects of
134 are stressed, the term
136 includes the GNU extensions, whereas
140 The main source of documentation for all aspects of the
142 is the groff info file. The manual page
143 .BR groff (@MAN7EXT@)
144 gives a short description of all predefined language elements.
146 Documents using roff are normal text files decorated by formatting
148 It is very easy to write high-quality documents by using one of the
150 These are like high-level programming languages, while the bare roff
151 language compares to a low-level language like C or assembler.
153 The roff language is a full programming language providing low-level
154 requests, definition of macros, escape sequences, string variables,
155 number or size registers, and C-like flow controls.
157 In the 1980s, it was even possible to write the common utilities for
158 system administration by only using troff.
159 There were contests on writing the most unreadable program fake by
160 exclusively using troff.
161 Because of security impacts, these dangerous features were removed in
165 Some clarification on the language elements seems to be wanted.
166 Requests are basic formatting commands defined by programming languages
167 like C, C++, etc., whereas macros are formatting commands that are
168 written in the roff language.
169 A document writer will not note any difference in usage for requests or
170 macros, both are written on a line on their own starting with a dot
172 But the user may define her own macros if desired.
174 Escape sequences are in-line elements starting with a backslash
176 They are used to implement various features, including the insertion of
177 non-ASCII characters with
179 the content of strings with
181 and register variables with
185 in-line comments with
187 the escaping of special control characters like
189 and many other features.
190 .\" --------------------------------------------------------------------
192 .\" --------------------------------------------------------------------
193 Formatters are the front-end programs that analyze a groff document and
194 translate it into a form that is suitable for a special device.
201 for graphical devices.
203 These programs still exist in the
205 implementation, but usually they are accessed through a program called
207 This combined and extended the old functionality into a single program.
208 It has many command-line options, most of them herited from
210 To ease the option jungle, the user-friendly utility
212 (from `groff guess') was created.
213 It tries to guess from the document which arguments should be used and
214 displays a suitable command line.
215 Though not being perfect, it is a good starting point.
216 .\" --------------------------------------------------------------------
218 .\" --------------------------------------------------------------------
219 The classical preprocessors that are still available in groff.
225 for including mathematical equations.
228 for constructing graphical elements (this preprocessor doesn't come with
229 groff; it is an extra package).
232 for including gremlin pictures.
235 for creating diagrams.
238 for bibliographic references.
241 for including other roff files.
244 for rectangular tables.
248 Each of these preprocessors defines its own language that is translated
249 into roff code when run through the preprocessor program.
250 So parts written in these languages may be included within a roff
252 Such an enhanced document is run through one or more corresponding
253 preprocessors before it is fed into the actual formatter.
255 The preprocessor programs extract and transform the document parts
257 They can be called either in a UNIX pipeline with their program name or
258 automatically with a groff option.
261 center, box, tab (@);
264 preprocessor@groff option
276 .\" --------------------------------------------------------------------
278 .\" --------------------------------------------------------------------
279 Macro packages are collections of macros that are suitable to format a
280 special kind of documents in a convenient way.
281 This greatly eases the usage of roff.
282 The macro definitions of a package are kept in a file called
288 is the internal roff name for this package.
289 All tmac files are stored in a single or few directories at standard
292 A macro package that is used in a document is specified by the command line
295 for the formatter like
301 General details on the naming of macro packages and their placement is
303 .BR groff_tmac (@MAN5EXT@).
305 Famous classical macro packages are
315 for books, articles, and letters.
316 Besides these collections, groff provides an increasing number of new
317 macro packages for various applications, for example integration of or
318 conversion into other file formats.
319 .\" --------------------------------------------------------------------
320 .SH "FILE NAME EXTENSIONS"
321 .\" --------------------------------------------------------------------
322 Manual pages (man-pages) take the section number as a file name
323 extension, e.g., the filename for this document is
326 .prefixednumber section 7
329 The classical macro packages take the package name as an extension, e.g.
331 for a document using the
347 But there is no general naming scheme for roff documents, though
351 seems to be a good choice.
353 File name extensions can be very handy in conjunction with the
356 It provides the possibility to feed all input into a command-line pipe that
357 is specified in the shell environment variable
359 This process is not well documented, so here an example
360 .B LESSOPEN='|lesspipe %s'
363 is either a system supplied command or a shell script of your own.
365 .\" --------------------------------------------------------------------
367 .\" --------------------------------------------------------------------
368 Most text editors provide support for editing documents using roff.
369 Especially useful is the
371 in all flavors of the Emacs editor.
372 .\" --------------------------------------------------------------------
374 .\" --------------------------------------------------------------------
378 A colon separated list of directories in which to search for
380 .BR groff_tmac (@MAN5EXT@).
388 A colon separated list of directories in which to search for the
392 will first search in directories given with the
394 command line option, then in
395 .BR GROFF_FONT_PATH ,
396 and finally in the standard directories
398 .\" --------------------------------------------------------------------
400 .\" --------------------------------------------------------------------
403 installs all of its data files in subdirectories of
407 (except wrapper files for system-specific macro packages which will be
409 .IR @SYSTEMMACRODIR@ ).
410 These locations might vary for different systems.
411 In the following, the former is referred to as
412 .IR <groff_font_dir> ,
414 .IR <groff_macro_dir> .
416 .IB <groff_macro_dir> /troffrc
417 Initialization file for troff.
419 .IB <groff_macro_dir> / name .tmac
421 .IB <groff_macro_dir> /tmac. name
424 .IB <groff_font_dir> /dev name /DESC
425 Device description file for device
428 .IB <groff_font_dir> /dev name / F
434 Finally, a local macro directory
436 is provided for site-specific macros and packages; by default, it will be
437 searched before the main macro directory.
438 .\" --------------------------------------------------------------------
440 .\" --------------------------------------------------------------------
441 The groff documentation is in evolution at the moment.
442 It is possible that small inconsistencies between different documents exist
444 .\" --------------------------------------------------------------------
446 .\" --------------------------------------------------------------------
447 This document is part of groff, the GNU roff distribution. It was
448 written by Bernd Warken <bwarken@mayn.de>.
450 It is distributed under the terms of the FDL (GNU Free Documentation
451 License) version 1.1 or later. You should have received a copy of the
452 FDL on your system, it is also available on-line under
455 .IR <http://www.gnu.org/copyleft/fdl.html> .
457 .\" --------------------------------------------------------------------
459 .\" --------------------------------------------------------------------
460 The main source of information is the
465 The predefined elements of the
467 language are also documented in the manual page
468 .BR groff (@MAN7EXT@).
470 Formatters and their wrappers:
471 .BR groff (@MAN1EXT@),
472 .BR grog (@MAN1EXT@),
473 .BR nroff (@MAN1EXT@),
475 .BR troff (@MAN1EXT@).
477 Postprocessors for the output devices:
478 .BR grodvi (@MAN1EXT@),
479 .BR grohtml (@MAN1EXT@),
480 .BR grolbp (@MAN1EXT@),
481 .BR grolj4 (@MAN1EXT@),
482 .BR grops (@MAN1EXT@),
484 .BR grotty (@MAN1EXT@).
486 Standard preprocessors:
491 .BR refer (@MAN1EXT@),
492 .BR soelim (@MAN1EXT@),
496 The man pages for macro packages include
497 .BR groff_tmac (@MAN5EXT@),
498 .BR groff_man (@MAN7EXT@),
499 .BR groff_markup (@MAN7EXT@),
500 .BR groff_mdoc (@MAN7EXT@),
501 .BR groff_mdoc.samples (@MAN7EXT@),
502 .BR groff_me (@MAN7EXT@),
503 .BR groff_mm (@MAN7EXT@),
504 .BR groff_mmroff (@MAN7EXT@),
506 .BR groff_ms (@MAN7EXT@).
508 The following utilities are available:
509 .BR addftinfo (@MAN1EXT@),
510 .BR afmtodif (@MAN1EXT@),
511 .BR hpftodit (@MAN1EXT@),
512 .BR indxbib (@MAN1EXT@),
513 .BR lookbib (@MAN1EXT@),
514 .BR pfbtops (@MAN1EXT@),
515 .BR tfmtodit (@MAN1EXT@),
517 .BR gxditview (@MAN1EXT@).
519 For details on the GNU implementation of the
522 .BR groff_char (@MAN7EXT@),
523 .BR groff_font (@MAN7EXT@),
524 .BR groff_out (@MAN7EXT@),
527 in the main directory of the groff source distribution.
528 These also give details on how to contact or join the
534 documents are still available on-line.
535 Especially informative are the original Bell Labs proceedings for the old,
537 .I http://cm.bell-labs.com/cm/cs/cstr.html
538 and the collection of the late Richard S. Stevens at
539 .IR http://www.kohala.com/start/troff/ .