Penguin
Recent Changes
Annotated edit history of roff(7) version 4, including all changes. View license author blame.
Rev Author # Line
1 perry 1 ROFF
2 !!!ROFF
3 NAME
4 DESCRIPTION
5 FORMATTING LANGUAGE
6 FORMATTERS
7 PREPROCESSORS
8 MACRO PACKAGES
9 FILE NAME EXTENSIONS
10 EDITING
11 ENVIRONMENT
12 FILES
13 BUGS
14 AUTHOR
15 SEE ALSO
16 ----
17 !!NAME
18
19
20 roff - a survey of the roff typesetting system
21 !!DESCRIPTION
22
23
24 ''roff'' is the general name for a set of type-setting
25 programs, known under names like ''troff'', ''nroff'',
26 ''groff'', etc.
27
28
29 The roff type-setting system consists of a formatting
30 language, macro packages, preprocessors, postprocessors for
31 output devices, user front-end programs, and conversion
32 tools.
33
34
35 The most common roff system today is the free software
36 implementation ''groff'' (from `GNU roff'). The pre-groff
37 implementations are referred to as `classical' (dating back
38 as long as 1973).
39
40
41 ''groff'' is backward-compatible to its classical
42 ancestors, but has many extensions, and is still evolving.
43 As it is available for almost every computer system it is
44 the de-facto roff standard today.
45
46
47 In spite of its age, roff is in wide use today, e.g., the
48 manual pages on UNIX systems (''man-pages'') are written
49 in roff. The roff output for text devices is still
50 unmatched, and its graphical output has the same quality as
51 the other free type-setting programs and is better than some
52 of the commercial systems.
53
54
55 This document gives only an overview and provides pointers
56 to further documentation.
57
58
59 This document is not maintained and might be out of date.
60 For the real documentation refer to the groff info file that
61 contains the detailed, actual and concise reference
62 information.
63 !!FORMATTING LANGUAGE
64
65
66 There are three terms that refer to the language of the
67 ''roff'' system. The term ''troff language'' is used
68 when the classical aspects of ''roff'' are stressed, the
69 term ''groff language'' includes the GNU extensions,
70 whereas ''roff language'' is the general
71 term.
72
73
74 The main source of documentation for all aspects of the
75 ''groff language'' is the groff info file. The manual
76 page groff(7) gives a short description of all
77 predefined language elements.
78
79
80 Documents using roff are normal text files decorated by
81 formatting elements. It is very easy to write high-quality
82 documents by using one of the macro packages. These are like
83 high-level programming languages, while the bare roff
84 language compares to a low-level language like C or
85 assembler.
86
87
88 The roff language is a full programming language providing
89 low-level requests, definition of macros, escape sequences,
90 string variables, number or size registers, and C-like flow
91 controls.
92
93
94 Some clarification on the language elements seems to be
95 wanted. Requests are basic formatting commands defined by
96 programming languages like C, C++, etc., whereas macros are
97 formatting commands that are written in the roff language. A
98 document writer will not note any difference in usage for
99 requests or macros, both are written on a line on their own
100 starting with a dot `.'. But the user may define her own
101 macros if desired.
102
103
104 Escape sequences are in-line elements starting with a
105 backslash `'. They are used to implement various features,
106 including the insertion of non-ASCII characters with , the
107 content of strings with * and register variables with n,
108 font changes with f, in-line comments with \(
109 !!FORMATTERS
110
111
112 Formatters are the front-end programs that analyze a groff
113 document and translate it into a form that is suitable for a
114 special device. The traditional ''roff'' had two
115 formatters, __nroff__ for text devices and __troff__
116 for graphical devices.
117
118
119 These programs still exist in the ''groff''
120 implementation, but usually they are accessed through a
121 program called __groff__. This combined and extended the
122 old functionality into a single program. It has many
123 command-line options, most of them herited from
124 __troff__. To ease the option jungle, the user-friendly
125 utility __grog__ (from `groff guess') was created. It
126 tries to guess from the document which arguments should be
127 used and displays a suitable command line. Though not being
128 perfect, it is a good starting point.
129 !!PREPROCESSORS
130
131
132 The classical preprocessors that are still available in
133 groff.
134
135
136 ''eqn''
137
138
139 for including mathematical equations.
140
141
142 ''grap''
143
144
145 for constructing graphical elements (this preprocessor
146 doesn't come with groff; it is an extra
147 package).
148
149
150 ''grn''
151
152
153 for including gremlin pictures.
154
155
156 ''pic''
157
158
159 for creating diagrams.
160
161
162 ''refer''
163
164
165 for bibliographic references.
166
167
168 ''soelim''
169
170
171 for including other roff files.
172
173
174 ''tbl''
175
176
177 for rectangular tables.
178
179
180 Each of these preprocessors defines its own language that is
181 translated into roff code when run through the preprocessor
182 program. So parts written in these languages may be included
183 within a roff document. Such an enhanced document is run
184 through one or more corresponding preprocessors before it is
185 fed into the actual formatter.
186
187
188 The preprocessor programs extract and transform the document
189 parts determined for them. They can be called either in a
190 UNIX pipeline with their program name or automatically with
191 a groff option.
192 !!MACRO PACKAGES
193
194
195 Macro packages are collections of macros that are suitable to format a special kind of documents in a convenient way. This greatly eases the usage of roff. The macro definitions of a package are kept in a file called ''name''__.tmac__ (or __tmac.__''name'') where ''name'' is the internal roff name for this package. All tmac files are stored in a single or few directories at standard positions.
196
197
198 A macro package that is used in a document is specified by
199 the command line option -m for the formatter like troff -m
200 name or groff -m name. General details on the naming of
201 macro packages and their placement is found in
4 perry 202 groff_tmac(5).
1 perry 203
204
205 Famous classical macro packages are ''man'',
206 ''mandoc'', and ''mdoc'' for manual pages and
207 ''me'', ''ms'', and ''mm'' for books, articles, and
208 letters. Besides these collections, groff provides an
209 increasing number of new macro packages for various
210 applications, for example integration of or conversion into
211 other file formats.
212 !!FILE NAME EXTENSIONS
213
214
215 Manual pages (man-pages) take the section number as a file
216 name extension, e.g., the filename for this document is
217 ''roff.7'', i.e., it is kept in section 7 of the
218 man-pages.
219
220
221 The classical macro packages take the package name as an
222 extension, e.g. ''file.''__me__ for a document using
223 the ''me'' macro package, ''file.''__mm__ for
224 ''mm'', ''file.''__ms__ for ''ms'',
225 ''file.''__pic__ for ''pic'' files,
226 etc.
227 !!EDITING
228
229
230 Most text editors provide support for editing documents
231 using roff. Especially useful is the __nroff-mode__ in
232 all flavors of the Emacs editor.
233 !!ENVIRONMENT
234
235
236 __GROFF_TMAC_PATH__
237
238
239 A colon separated list of directories in which to search for
4 perry 240 macro files, see groff_tmac(5).
1 perry 241
242
243 __GROFF_TYPESETTER__
244
245
246 Default device.
247
248
249 __GROFF_FONT_PATH__
250
251
252 A colon separated list of directories in which to search for
253 the __dev__''name'' directory. __troff__ will first
254 search in directories given with the -F command line option,
255 then in __GROFF_FONT_PATH__, and finally in the standard
256 directories
257 (__/usr/share/groff/1.17.2/font:/usr/lib/font__).
258 !!FILES
259
260
261 By default, ''groff'' installs all of its data files in
262 subdirectories of ''/usr/share/groff/1.17.2/font'' and in
263 ''/usr/share/groff/1.17.2/tmac'' (except wrapper files
264 for system-specific macro packages which will be in
265 ''/usr/lib/groff/site-tmac''). These locations might vary
266 for different systems. In the following, the former is
267 referred to as '''', the latter as
268 ''''.
269
270
271 ''''__/troffrc__
272
273
274 Initialization file for troff.
275
276
277 ''''__/__''name''__.tmac__
278
279
280 ''''__/tmac.__''name''
281
282
283 Macro files.
284
285
286 ''''__/dev__''name''__/DESC__
287
288
289 Device description file for device ''name''.
290
291
292 ''''__/dev__''name''__/__''F''
293
294
295 Font file for font ''F'' of device
296 ''name''.
297
298
299 Finally, a local macro directory
300 ''/usr/share/groff/site-tmac'' is provided for
301 site-specific macros and packages; by default, it will be
302 searched before the main macro directory.
303 !!BUGS
304
305
306 The groff documentation is in evolution at the moment. It is
307 possible that small inconsistencies between different
308 documents exist temporarily.
309 !!AUTHOR
310
311
312 This document is part of groff, the GNU roff distribution.
313 It was written by Bernd Warken
314
315
316 It is distributed under the terms of the FDL (GNU Free
317 Documentation License) version 1.1 or later. You should have
318 received a copy of the FDL on your system, it is also
319 available on-line under
320
321
322 ''''.
323 !!SEE ALSO
324
325
326 The main source of information is the ''groff''
327 info(1) file.
328
329
330 The predefined elements of the ''groff'' language are
331 also documented in the manual page
332 groff(7).
333
334
335 Formatters and their wrappers: groff(1),
336 grog(1), nroff(1), and
337 troff(1).
338
339
340 Postprocessors for the output devices: grodvi(1),
4 perry 341 grohtml(1), grolbp(1), grolj4(1),
1 perry 342 grops(1), and grotty(1).
343
344
345 Standard preprocessors: eqn(1), grn(1),
346 grap(1), pic(1), refer(1),
347 soelim(1), and tbl(1).
348
349
350 The man pages for macro packages include
4 perry 351 groff_tmac(5), __groff_man__(7),
352 groff_markup(7), __groff_mdoc__(7),
353 groff_mdoc.samples(7), __groff_me__(7),
354 groff_mm(7), __groff_mmroff__(7), and
355 groff_ms(7).
1 perry 356
357
358 The following utilities are available: addftinfo(1),
359 afmtodif(1), hpftodit(1), indxbib(1),
360 lookbib(1), pfbtops(1), tfmtodit(1),
361 and gxditview(1).
362
363
364 For details on the GNU implementation of the ''roff''
4 perry 365 system see groff_char(7), __groff_font__(7),
366 groff_out(7), and the file ''README'' in the main
1 perry 367 directory of the groff source distribution. These also give
368 details on how to contact or join the ''groff'' developer
369 group.
370
371
372 Many classical documents are still available on-line.
373 Especially informative are the original Bell Labs
374 proceedings for the old, free UNIX 7 found at
375 ''http://cm.bell-labs.com/cm/cs/cstr.html'' and the
376 collection of the late Richard S. Stevens at
377 ''http://www.kohala.com/start/troff/''.
378 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.