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/ .
added
removed
man/roff.man
