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