| blob | f51c215e89ebbe01c10893aee43b85717d6b518c |
1 .\" -*- nroff -*-
2 .ig
3 roff.7
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: 28 Apr 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 AUTHOR, with no Front-Cover Texts, and with no
16 Back-Cover Texts.
18 A copy of the Free Documentation License is included as a file called
19 fdl.txt in the main directory of the groff source package.
20 ..
21 .\" --------------------------------------------------------------------
22 .\" Setup
23 .\" --------------------------------------------------------------------
24 .de MP
25 . ds @tmp@ \\fB\\$1\\fP\\fR(\\$2)\\fP
26 . shift 2
27 \\*[@tmp@]\\$*
28 . rm @tmp@
29 ..
30 .de BIR
31 .ie \\n[.$]<3 .BI $@
32 .el \{\
33 . ds @tmp@ \\fB\\$1\\fP\\fI\\$2\\fP
34 . shift 2
35 \\*[@tmp@]\\fR\\$*\\fP
36 . rm @tmp@
37 .\}
38 ..
39 .ds dquote \&"
40 .ds dquote \&"\" make Emacs happy
41 .\" --------------------------------------------------------------------
42 .\" Title
43 .\" --------------------------------------------------------------------
44 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
45 .SH NAME
46 roff \- a survey of the roff typesetting system
47 .\" --------------------------------------------------------------------
48 .SH DESCRIPTION
49 .\" --------------------------------------------------------------------
50 .I roff
51 is the general name for a set of type-setting programs, known under
52 names like
53 .IR troff ,
54 .IR nroff ,
55 .IR groff ,
56 etc.
57 .LP
58 The
59 .I roff
60 type-setting system consists of a formatting language, macro packages,
61 preprocessors, postprocessors for output devices, user front-end
62 programs, and conversion tools.
63 .LP
64 The most common
65 .I roff
66 system today is the free software implementation
67 .I groff
68 (from "GNU\ roff").
69 The pre-groff implementations are referred to as "classical" (dating
70 back as long as 1973).
71 .LP
72 .I groff
73 is backward-compatible to its classical ancestors, but has many
74 extensions, and is still evolving.
75 As it is available for almost every computer systems it is the de-facto
76 .I roff
77 standard today.
78 .LP
79 In spite of its age,
80 .I roff
81 is in wide use today, e.g., the manual pages on UNIX systems
82 .RI ( man
83 .IR pages )
84 are written in
85 .IR roff .
86 Its output for text devices is still unmatched, and its graphical output
87 has the same quality as the other free type-setting programs and is
88 better than some of the commercial systems.
89 .LP
90 This document gives only an overview and provides pointers to further
91 documentation.
92 This document is not maintained and might be out of date.
93 For the real documentation refer to the
94 .I groff
95 info file.
96 It contains more detailed, actual and concise information.
97 .\" --------------------------------------------------------------------
98 .SH "FORMATTING LANGUAGE"
99 .\" --------------------------------------------------------------------
100 There are three terms that refer to the language of the
101 .I roff
102 system. The term
103 .I troff language
104 is used when the classical aspects of
105 .I roff
106 are stressed, the term
107 .I groff language
108 includes the GNU extensions, whereas
109 .I roff language
110 is the general term.
111 .LP
112 The main source of documentation for all aspects of the
113 .I groff language
114 is the groff info file. The manual page
115 .BR groff (@MAN7EXT@)
116 gives a short description of all predefined language elements.
117 .LP
118 .I roff
119 documents are normal text files decorated by formatting elements.
120 It is very easy to write high-quality documents by using one of the macro
121 packages.
122 These are like high-level programming languages, while the bare
123 .I roff
124 language compares to a low-level language like C or assembler.
125 .LP
126 The
127 .I roff
128 language is a full programming language providing low-level requests,
129 definition of macros, escape sequences, string variables, number or size
130 registers, and C-like flow controls.
131 In the 1980s, it was even possible to write the common utilities for system
132 administration by only using
133 .IR troff .
134 There were contests on writing the most unreadable program fake by
135 exclusively using
136 .IR troff .
137 Because of security impacts, these dangerous features were removed in
138 .IR groff .
139 .LP
140 Some clarification on the language elements seems to be wanted.
141 Requests are basic formatting commands defined by programming languages
142 like C, C++, etc., whereas macros are formatting commands that are
143 written in the
144 .I roff
145 language.
146 A document writer will not note any difference in usage for requests or
147 macros, both are written on a line on their own starting with a dot `.'.
148 But the user may define her own macros if desired.
149 .LP
150 Escape sequences are in-line elements starting with a backslash `\e'.
151 They are used to implement various features, including the insertion of
152 non-ASCII characters with \fB\e(\fP, the content of strings with
153 \fB\e*\fP and register variables with \fB\en\fP, font changes with
154 \fB\ef\fP, in-line comments with \fB\e\*[dquote]\fP, the escaping of
155 special characters used in the
156 .I roff
157 language like \fB\e\e\fP, and many other features.
158 .\" --------------------------------------------------------------------
159 .SH FORMATTERS
160 .\" --------------------------------------------------------------------
161 Formatters are the front-end programs that analize a groff document and
162 translate it into a form that is suitable for a special device.
163 The traditional
164 .I roff
165 had two formatters,
166 .B nroff
167 for text devices and
168 .B troff
169 for graphical devices.
170 .LP
171 These programs still exist in the
172 .I groff
173 implementation, but usually they are accessed thru a program called
174 .BR groff .
175 This combined and extended the old functionality into a single program.
176 It has many command-line options, most of them herited from
177 .BR troff .
178 To ease the option jungle, the user-friendly utility
179 .B grog
180 (from "groff guess") was created.
181 It tries to guess from the document which arguments should be used and
182 displays a suitable command line.
183 Though not being perfect, it is a good starting point.
184 .\" --------------------------------------------------------------------
185 .SH PREPROCESSORS
186 .\" --------------------------------------------------------------------
187 There are 4 classical preprocessors that are still available in
188 .IR groff :
189 .I eqn
190 for including mathematical equations,
191 .I pic
192 for creating diagrams,
193 .I tbl
194 for rectangular tables, and
195 .I soelim
196 for including other roff files into a document.
197 There were many more preprocessors available in industrial roff
198 implementations.
199 By the time, some of these will be available in groff as well, e.g., grap
200 has been actually developed.
201 .LP
202 Each of these preprocessors defines a language that is translated into
203 roff code when run through the preprocessor program.
204 So parts written in these languages may be included within a roff document.
205 Such an enhanced document is run thru one or more corresponding
206 preprocessors before it is fed into the actual formatter.
207 .L
208 The preprocessors programs are called
209 .BR eqn ,
210 .BR pic ,
211 .BR tbl ,
212 and
213 .B soelim
214 respectively
215 They extract and transform the document parts determined for them.
216 .LP
217 The preprocessor programs can be used within a UNIX pipeline like
218 .LP
219 .RS
220 .B cat
221 .I file
222 .B | tbl | groff ...
223 .RE
224 .LP
225 Alternatively, each one can be activated by a single character option when
226 calling
227 .BR groff .
228 .LP
229 The option letters are easy to remember, classical
230 .B troff
231 as well as
232 .B groff
233 use the first character of the preprocessor, i.e.,
234 .BR -e ,
235 .BR -p ,
236 .BR -t ,
237 and
238 .B -s
239 resp.
240 .\" --------------------------------------------------------------------
241 .SH "MACRO PACKAGES"
242 .\" --------------------------------------------------------------------
243 Macro packages are collections of macros that are suitable to format a
244 special kind of documents in a convenient way.
245 This greatly eases the usage of
246 .IR roff .
247 The macro definitions of a package are kept in a file called
248 .I tmac.<name>
249 where
250 .I <name>
251 is the internal
252 .I roff
253 name for this package.
254 All tmac files are stored in a single or few directories at standard
255 positions.
256 .LP
257 A macro package that is used in a document is specified by the command line
258 option
259 .B -m
260 for the formatter like
261 .BI "troff\ -m "\ name
262 or
263 .BIR "troff\ -m" name .
264 General details on the naming of macro packages and their placement is
265 found in
266 .BR tmac (@MAN5EXT@).
267 .LP
268 Famous classical macro packages are
269 .IR man ,
270 .IR mandoc ,
271 and
272 .I mdoc
273 for manual pages and
274 .IR me ,
275 .IR ms ,
276 and
277 .I mm
278 for books, articles, and letters.
279 Besides these collections,
280 .I groff
281 provides an increasing multitude of new macro packages for various
282 applications, for example integration of or conversion into other file
283 formats.
284 .\" --------------------------------------------------------------------
285 .SH "FILE NAME EXTENSIONS"
286 .\" --------------------------------------------------------------------
287 Manual pages (man-pages) take the section number as a file name
288 extension, e.g., the filename for this document is
289 .IR roff.7 ,
290 i.e., it is kept in section\ 7 of the man-pages.
291 .LP
292 The classical macro packages take the package name as an extension, e.g.
293 .IB file. me
294 for a document using the
295 .I me
296 macro package,
297 .IB file. mm
298 for
299 .IR mm ,
300 .IB file. ms
301 for
302 .IR ms ,
303 .IB file. pic
304 for
305 .I pic
306 files,
307 etc.
308 .LP
309 But there is no general naming scheme for roff documents, though
310 .IB file. roff
311 or
312 .IB file. rof
313 seems to be a good choice.
314 .LP
315 File name extensions can be very handy in conjunction with the
316 .MP less 1
317 pager.
318 It provides the possibility to feed all input into a command-line pipe that
319 is specified in the shell environment variable
320 .B LESSOPEN
321 This process is not well documented, so here an example
322 .B LESSOPEN='|lesspipe %s'
323 where
324 .B lesspipe
325 is either a system supplied command or a shell script of your own.
326 .\" --------------------------------------------------------------------
327 .SH EDITING
328 .\" --------------------------------------------------------------------
329 Most text editors provide support for editing documents using roff.
330 Especially useful is the
331 .B nroff-mode
332 in all flavors of the Emacs editor.
333 .\" --------------------------------------------------------------------
334 .SH ENVIRONMENT
335 .\" --------------------------------------------------------------------
336 .TP
337 .SM
338 .B GROFF_TMAC_PATH
339 A colon separated list of directories in which to search for
340 macro files, see
341 .TP
342 .SM
343 .B GROFF_TYPESETTER
344 Default device.
345 .TP
346 .SM
347 .B GROFF_FONT_PATH
348 A colon separated list of directories in which to search for the
349 .BI dev name
350 directory.
351 .B troff
352 will search in directories given in the
353 .B \-F
354 option before these, and in standard directories
355 .RB ( .:/usr/local/share/groff/font:/usr/lib/font )
356 after these.
357 .\" --------------------------------------------------------------------
358 .SH FILES
359 .\" --------------------------------------------------------------------
360 By default,
361 .I groff
362 installs all of its library files in a directory tree under
363 .IR /usr/local/share/groff .
364 This location might vary for different systems systems.
365 In the following, this directory is referred to as
366 .BR GROFF_DIR .
367 .LP
368 .TP
369 .B GROFF_DIR/tmac/troffrc
370 Initialization file
371 .TP
372 .BI GROFF_DIR/tmac/tmac. name
373 Macro files
374 .TP
375 .BI GROFF_DIR/font/dev name /DESC
376 Device description file for device
377 .IR name .
378 .TP
379 .BI GROFF_DIR/font/dev name / F
380 Font file for font
381 .I F
382 of device
383 .IR name .
384 .\" --------------------------------------------------------------------
385 .SH BUGS
386 .\" --------------------------------------------------------------------
387 The groff documentation is in evolution at the moment.
388 It is possible that small inconsistencies between different documents exist
389 temporarily.
390 .\" --------------------------------------------------------------------
391 .SH AUTHOR
392 .\" --------------------------------------------------------------------
393 This document was written by Bernd Warken <bwarken@mayn.de> and is part
394 of the GNU roff distribution.
395 .LP
396 It is distributed under the terms of the GFDL (GNU Free Documentation
397 License) version 1.1 or later.
398 You should have received a copy of the GFDL on your system, it is also
399 available on-line under
400 .IR <http://www.gnu.org/copyright/fdl.html> .
401 .\" --------------------------------------------------------------------
402 .SH "SEE ALSO"
403 .\" --------------------------------------------------------------------
404 The main source of information is the
405 .I groff
406 .MP info 1
407 file.
408 .LP
409 The predefined elements of the
410 .I groff
411 language are also documented in the manual page
412 .BR groff (@MAN7EXT@).
413 .LP
414 Formatters and their wrappers:
415 .BR groff (@MAN1EXT@),
416 .BR grog (@MAN1EXT@),
417 .BR nroff (@MAN1EXT@),
418 and
419 .BR troff (@MAN1EXT@).
420 .LP
421 Postprocessors for the output devices:
422 .BR grodvi (@MAN1EXT@),
423 .BR grohtml (@MAN1EXT@),
424 .BR grolbp (@MAN1EXT@),
425 .BR grolj4 (@MAN1EXT@),
426 .BR grops (@MAN1EXT@),
427 and
428 .BR grotty (@MAN1EXT@).
429 .LP
430 Standard preprocessors:
431 .BR eqn (@MAN1EXT@),
432 .BR grn (@MAN1EXT@),
433 .BR grap (1),
434 .BR pic (@MAN1EXT@),
435 .BR refer (@MAN1EXT@),
436 .BR soelim (@MAN1EXT@),
437 and
438 .BR tbl (@MAN1EXT@).
439 .LP
440 The man pages for macro packages include
441 .BR groff_tmac (@MAN5EXT@),
442 .BR groff_man (@MAN7EXT@),
443 .BR groff_markup (@MAN7EXT@),
444 .BR groff_mdoc (@MAN7EXT@),
445 .BR groff_mdoc.samples (@MAN7EXT@),
446 .BR groff_me (@MAN7EXT@),
447 .BR groff_mm (@MAN7EXT@),
448 .BR groff_mmroff (@MAN7EXT@),
449 .BR groff_ms (@MAN7EXT@),
450 and
451 .BR groff_msafer (@MAN7EXT@).
452 .LP
453 The following utils are available:
454 .BR addftinfo (@MAN1EXT@),
455 .BR afmtodif (@MAN1EXT@),
456 .BR hpftodit (@MAN1EXT@),
457 .BR indxbib (@MAN1EXT@),
458 .BR lookbib (@MAN1EXT@),
459 .BR pfbtops (@MAN1EXT@),
460 .BR tfmtodit (@MAN1EXT@),
461 and
462 .BR gxditview (@MAN1EXT@).
463 .LP
464 For details on the GNU implementation of the
465 .I roff
466 system see
467 .BR groff_char (@MAN7EXT@),
468 .BR groff_font (@MAN7EXT@),
469 .BR groff_out (@MAN7EXT@),
470 and the file
471 .I README
472 in the main directory of the groff source distribution.
473 These also give details on how to contact or join the
474 .I groff
475 developer group.
476 .LP
477 Many classical
478 .troff
479 documents are still available on-line.
480 Especially informative are the original Bell Labs proceedings for the old,
481 free UNIX 7 found at
482 .I http://cm.bell-labs.com/cm/cs/cstr.html
483 and the Collection of Richard S. Stevens at
484 .IR http://www.kohala.com/start/troff/ .