Penguin
Recent Changes
Blame: groff_man(7)
EditPageHistoryDiffInfoLikePages
Annotated edit history of groff_man(7) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 GROFF_MAN
2 !!!GROFF_MAN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 USAGE
8 MACROS TO SET FONTS
9 MISCELLANEOUS
10 FILES
11 SEE ALSO
12 AUTHOR
13 ----
14 !!NAME
15
16
17 groff_man - groff `man' macros to support generation of man pages
18 !!SYNOPSIS
19
20
21 __groff -man__ [[ ''options''... ] [[ ''files''...
22 ]__
23 groff -m man__ [[ ''options''... ] [[ ''files''...
24 ]
25 !!DESCRIPTION
26
27
28 The __man__ macros used to generate man pages with
29 ''groff'' were written by James Clark. This document
30 provides a brief summary of the use of each macro in that
31 package.
32 !!OPTIONS
33
34
35 The __man__ macros understand the following command line
36 options (which define various registers).
37
38
39 __-rcR=1__
40
41
42 This option (the default if in nroff mode) will create a
43 single, very long page instead of multiple pages. Say
44 __-rcR=0__ to disable it.
45
46
47 __-rC1__
48
49
50 If more than one manual page is given on the command line,
51 number the pages continuously, rather than starting each at
52 1.
53
54
55 __-rD1__
56
57
58 Double-sided printing. Footers for even and odd pages are
59 formatted differently.
60
61
62 __-rP__''nnn''
63
64
65 Enumeration of pages will start with ''nnn'' rather than
66 with 1.
67
68
69 __-rS__''xx''
70
71
72 Base document font size is ''xx'' points (''xx'' can
73 be 10, 11, or 12) rather than 10 points.
74
75
76 __-rX__''nnn''
77
78
79 After page ''nnn'', number pages as ''nnn''a,
80 ''nnn''b, ''nnn''c, etc. For example, the option
81 `-rX2' will produce the following page numbers: 1, 2, 2a,
82 2b, 2c, etc.
83 !!USAGE
84
85
86 This section describes the available macros for manual
87 pages. For further customization, put additional macros and
88 requests into the file __man.local__ which will be loaded
89 immediately after the __man__ package.
90
91
92 __.TH__ ''title section'' __[[__''extra1''__]
93 [[__''extra2''__]
94 [[__''extra3''__]__
95
96
97 Sets the title of the man page to ''title'' and the
98 section to ''section'', which must take on a value
99 between 1 and 8. The value ''section'' may also have a
100 string appended, e.g. `.pm', to indicate a specific
101 subsection of the man pages. Both ''title'' and
102 ''section'' are positioned at the left and right in the
103 header line (with ''section'' in parentheses immediately
104 appended to ''title''. ''extra1'' will be positioned
105 in the middle of the footer line. ''extra2'' will be
106 positioned at the left in the footer line (resp. at the left
107 on even pages and at the right on odd pages if double-sided
108 printing is active). ''extra3'' is centered in the header
109 line.
110
111
112 For HTML output, headers and footers are completely
113 supressed.
114
115
116 Additionally, this macro starts a new page; the new line
117 number is 1 again (except if the `-rC1' option is given on
118 the command line) -- this feature is intended only for
119 formatting multiple man pages; a single man page should
120 contain exactly one __TH__ macro at the beginning of the
121 file.
122
123
124 __.SH [[__''text for a heading''__]__
125
126
127 Sets up an unnumbered section heading sticking out to the
128 left. Prints out all the text following __SH__ up to the
129 end of the line (resp. the text in the next line if there is
130 no argument to __SH__) in bold face, one size larger than
131 the base document size. Additionally, the left margin for
132 the following text is reset to its default
133 value.
134
135
136 __.SS [[__''text for a heading''__]__
137
138
139 Sets up an secondary, unnumbered section heading. Prints out
140 all the text following __SS__ up to the end of the line
141 (resp. the text in the next line if there is no argument to
142 __SS__) in bold face, at the same size as the base
143 document size. Additionally, the left margin for the
144 following text is reset to its default value.
145
146
147 __.TP [[__''nnn''__]__
148
149
150 Sets up an indented paragraph with label. The indentation is
151 set to ''nnn'' if that argument is supplied (the default
152 unit is `n' if omitted), otherwise it is set to the default
153 indentation value. The first line of text following this
154 macro is interpreted as a string to be printed flush-left,
155 as it is appropriate for a label. It is not interpreted as
156 part of a paragraph, so there is no attempt to fill the
157 first line with text from the following input lines.
158 Nevertheless, if the label is not as wide as the
159 indentation, then the paragraph starts at the same line (but
160 indented), continuing on the following lines. If the label
161 is wider than the indentation, then the descriptive part of
162 the paragraph begins on the line following the label,
163 entirely indented. Note that neither font shape nor font
164 size of the label is set to a default value; on the other
165 hand, the rest of the text will have default font settings.
166 The __TP__ macro is the macro used for the explanations
167 you are just reading.
168
169
170 __.LP__
171
172
173 __.PP__
174
175
176 __.P__
177
178
179 These macros are mutual aliases. Any of them causes a line
180 break at the current position, followed by a vertical space
181 downwards by the amount specified by the __PD__ macro.
182 The font size and shape are reset to the default value (10pt
183 resp. Roman). Finally, the current left margin is
184 restored.
185
186
187 __.IP [[__''designator''__]
188 [[__''nnn''__]__
189
190
191 Sets up an indented paragraph, using ''designator'' as a
192 tag to mark its beginning. The indentation is set to
193 ''nnn'' if that argument is supplied (default unit is
194 `n'), otherwise the default indentation value is used. Font
195 size and face of the paragraph (but not the designator) are
196 reset to its default values. To start an indented paragraph
197 with a particular indentation but without a designator, use
198 `
199 ''
200
201
202 For example, the following paragraphs were all set up with
203 bullets as the designator, using `.IP 4':
204
205
206 __IP__ is one of the three macros used in the __man__
207 package to format lists.
208
209
210 __HP__ is another. This macro produces a paragraph with a
211 left hanging indentation.
212
213
214 __TP__ is another. This macro produces an unindented
215 label followed by an indented paragraph.
216
217
218 __.HP [[__''nnn''__]__
219
220
221 Sets up a paragraph with hanging left indentation. The
222 indentation is set to ''nnn'' if that argument is
223 supplied (default unit is `n'), otherwise the default
224 indentation value is used. Font size and face are reset to
225 its default values. The following paragraph illustrates the
226 effect of this macro with hanging indentation set to
227 4:
228
229
230 This is a paragraph following an invocation of the __HP__
231 macro. As you can see, it produces a paragraph where all
232 lines but the first are indented.
233
234
235 __.RS [[__''nnn''__]__
236
237
238 This macro moves the left margin to the right by the value
239 ''nnn'' if specified (default unit is `n'); otherwise the
240 default indentation value is used. Calls to the __RS__
241 macro can be nested.
242
243
244 __.RE [[__''nnn''__]__
245
246
247 This macro moves the left margin back to level ''nnn'';
248 if no argument is given, it moves one level back. The first
249 level (i.e., no call to __RS__ yet) has number 1, and
250 each call to __RS__ increases the level by
251 1.
252
253
254 To summarize, the following macros cause a line break with
255 the insertion of vertical space (which amount can be changed
256 with the __PD__ macro): __SH__, __SS__, __TP__,
257 __LP__ (__PP__, __P__), __IP__, and __HP__.
258 The macros __RS__ and __RE__ also cause a break but no
259 insertion of vertical space.
260 !!MACROS TO SET FONTS
261
262
263 The standard font is Roman; the default text size is 10
264 point.
265
266
267 __.SM [[__''text''__]__
268
269
270 Causes the text on the same line or the text on the next
271 line to appear in a font that is one point size smaller than
272 the default font.
273
274
275 __.SB [[__''text''__]__
276
277
278 Causes the text on the same line or the text on the next
279 line to appear in boldface font, one point size smaller than
280 the default font.
281
282
283 __.BI__ ''text''
284
285
286 Causes text on the same line to appear alternately in bold
287 face and italic. The text must be on the same line as the
288 macro call. Thus
289
290
291 .BI this
292
293
294 would cause `this' and `that' to appear in bold face, while
295 `word and' appears in italics.
296
297
298 __.IB__ ''text''
299
300
301 Causes text to appear alternately in italic and bold face.
302 The text must be on the same line as the macro
303 call.
304
305
306 __.RI__ ''text''
307
308
309 Causes text on the same line to appear alternately in roman
310 and italic. The text must be on the same line as the macro
311 call.
312
313
314 __.IR__ ''text''
315
316
317 Causes text on the same line to appear alternately in italic
318 and roman. The text must be on the same line as the macro
319 call.
320
321
322 __.BR__ ''text''
323
324
325 Causes text on the same line to appear alternately in bold
326 face and roman. The text must be on the same line as the
327 macro call.
328
329
330 __.RB__ ''text''
331
332
333 Causes text on the same line to appear alternately in roman
334 and bold face. The text must be on the same line as the
335 macro call.
336
337
338 __.R [[__''text''__]__
339
340
341 Causes ''text'' to appear in roman font. If no text is
342 present on the line where the macro is called, then the text
343 of the next line appears in roman. This is the default font
344 to which text is returned at the end of processing of the
345 other macros.
346
347
348 __.B [[__''text''__]__
349
350
351 Causes ''text'' to appear in bold face. If no text is
352 present on the line where the macro is called, then the text
353 of the next line appears in bold face.
354
355
356 __.I [[__''text''__]__
357
358
359 Causes ''text'' to appear in italic. If no text is
360 present on the line where the macro is called, then the text
361 of the next line appears in italic.
362 !!MISCELLANEOUS
363
364
365 The default indentation is 7.2n for all output devices
366 except for __grohtml__ which ignores
367 indentation.
368
369
370 __.DT__
371
372
373 Sets tabs every 0.5 inches. Since this macro is always
374 called during a __TH__ request, it makes sense to call it
375 only if the tab positions have been changed.
376
377
378 __.PD [[__''nnn''__]__
379
380
381 Adjusts the empty space before a new paragraph (resp.
382 section). The optional argument gives the amount of space
383 (default units are `v'); without parameter, the value is
384 reset to its default value (1 line for tty devices, 0.4v
385 otherwise). This affects the macros __SH__, __SS__,
386 __TP__, __LP__ (resp. __PP__ and __P__),
387 __IP__, and __HP__.
388
389
390 The following strings are defined:
391
392
393 __*S__
394
395
396 Switch back to the default font size.
397
398
399 __*R__
400
401
402 The `registered' sign.
403
404
405 __*(Tm__
406
407
408 The `trademark' sign.
409
410
411 __*(lq__
412
413
414 __*(rq__
415
416
417 Left and right quote. This is equal to ` and `
418 respectively.
419
420
421 If a preprocessor like __tbl__ or __eqn__ is needed,
422 it has become usage to make the first line of the man page
423 look like this:
424
425
426 __.__ ''word''
427
428
429 Note the single space character after the double quote.
430 ''word'' consists of letters for the needed
431 preprocessors: `e' for __eqn__, `r' for __refer__, and
432 `t' for __tbl__. Modern implementations of the __man__
433 program read this first line and automatically call the
434 right preprocessor(s).
435 !!FILES
436
437
438 __man.tmac__
439
440
441 __an.tmac__
442
443
444 These are wrapper files to call
445 __andoc.tmac__.
446
447
448 __andoc.tmac__
449
450
451 This file checks whether the __man__ macros or the
452 __mdoc__ package should be used.
453
454
455 __an-old.tmac__
456
457
458 All __man__ macros are contained in this
459 file.
460
461
462 __man.local__
463
464
465 Local changes and customizations should be put into this
466 file.
467 !!SEE ALSO
468
469
470 Since the __man__ macros consist of groups of
471 ''groff'' requests, one can, in principle, supplement the
472 functionality of the __man__ macros with individual
473 ''groff'' requests where necessary. A complete list of
474 these requests is available on the WWW at
475 http://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html
476 tbl(1), eqn(1), refer(1),
477 man(1)
478 !!AUTHOR
479
480
481 This manual page was originally written for the Debian GNU/Linux system by Susan G. Kleinmann
482 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.