]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler |
2 | .\" (faith@cs.unc.edu and dwheeler@ida.org) | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu) | |
27 | .\" Modified Sat Jun 8 00:39:52 1996 by aeb | |
28 | .\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org) | |
29 | .\" Modified Thu Jul 15 12:43:28 1999 by aeb | |
fea681da MK |
30 | .\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze <joey@infodrom.org> |
31 | .\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org> | |
a5e87f42 | 32 | .\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7. |
fea681da | 33 | .\" |
608bf950 | 34 | .TH MAN 7 2012-08-05 "Linux" "Linux Programmer's Manual" |
fea681da MK |
35 | .SH NAME |
36 | man \- macros to format man pages | |
37 | .SH SYNOPSIS | |
38 | .B groff \-Tascii \-man | |
39 | .I file | |
40 | \&... | |
41 | .LP | |
42 | .B groff \-Tps \-man | |
43 | .I file | |
44 | \&... | |
45 | .LP | |
46 | .B man | |
47 | .RI [ section ] | |
48 | .I title | |
49 | .SH DESCRIPTION | |
50 | This manual page explains the | |
add00eab | 51 | .B "groff an.tmac" |
fea681da MK |
52 | macro package (often called the |
53 | .B man | |
e7cbacd4 | 54 | macro package). |
fea681da | 55 | This macro package should be used by developers when |
c13182ef MK |
56 | writing or porting man pages for Linux. |
57 | It is fairly compatible with other | |
fea681da MK |
58 | versions of this macro package, so porting man pages should not be a major |
59 | problem (exceptions include the NET-2 BSD release, which uses a totally | |
60 | different macro package called mdoc; see | |
61 | .BR mdoc (7)). | |
62 | .PP | |
63 | Note that NET-2 BSD mdoc man pages can be used with | |
64 | .B groff | |
65 | simply by specifying the | |
66 | .B \-mdoc | |
67 | option instead of the | |
68 | .B \-man | |
c13182ef MK |
69 | option. |
70 | Using the | |
fea681da MK |
71 | .B \-mandoc |
72 | option is, however, recommended, since this will automatically detect which | |
73 | macro package is in use. | |
e7cbacd4 MK |
74 | .PP |
75 | For conventions that should be employed when writing man pages | |
76 | for the Linux \fIman-pages\fP package, see | |
77 | .BR man-pages (7). | |
78 | .SS Title line | |
988db661 | 79 | The first command in a man page (after comment lines, |
e6b9359d | 80 | that is, lines that start with \fB.\\"\fP) should be |
fea681da MK |
81 | .RS |
82 | .sp | |
83 | .B \&.TH | |
0daa9e92 | 84 | .I "title section date source manual" |
fea681da MK |
85 | .sp |
86 | .RE | |
aeb9b6a6 MK |
87 | For details of the arguments that should be supplied to the |
88 | .B TH | |
e7cbacd4 MK |
89 | command, see |
90 | .BR man-pages (7). | |
fea681da MK |
91 | .PP |
92 | Note that BSD mdoc-formatted pages begin with the | |
93 | .B Dd | |
94 | command, not the | |
95 | .B TH | |
96 | command. | |
e6b9359d | 97 | .SS Sections |
fea681da MK |
98 | Sections are started with |
99 | .B \&.SH | |
c13182ef | 100 | followed by the heading name. |
e6b9359d | 101 | .\" The following doesn't seem to be required (see Debian bug 411303), |
dc936104 MK |
102 | .\" If the name contains spaces and appears |
103 | .\" on the same line as | |
104 | .\" .BR \&.SH , | |
105 | .\" then place the heading in double quotes. | |
e6b9359d | 106 | |
226ae424 | 107 | The only mandatory heading is NAME, which should be the first section and |
a1712680 | 108 | be followed on the next line by a one-line description of the program: |
fea681da MK |
109 | .RS |
110 | .sp | |
111 | \&.SH NAME | |
112 | .br | |
a1712680 | 113 | item \\- description |
fea681da MK |
114 | .sp |
115 | .RE | |
116 | It is extremely important that this format is followed, and that there is a | |
a1712680 | 117 | backslash before the single dash which follows the item name. |
c13182ef | 118 | This syntax is used by the |
a1712680 MK |
119 | .BR mandb (8) |
120 | program to create a database of short descriptions for the | |
fea681da MK |
121 | .BR whatis (1) |
122 | and | |
123 | .BR apropos (1) | |
124 | commands. | |
a1712680 MK |
125 | (See |
126 | .BR lexgrog (1) | |
127 | for further details on the syntax of the NAME section.) | |
fea681da | 128 | .PP |
e7cbacd4 MK |
129 | For a list of other sections that might appear in a manual page, see |
130 | .BR man-pages (7). | |
e6b9359d | 131 | .SS Fonts |
fea681da MK |
132 | The commands to select the type face are: |
133 | .TP 4 | |
134 | .B \&.B | |
135 | Bold | |
136 | .TP | |
137 | .B \&.BI | |
138 | Bold alternating with italics | |
139 | (especially useful for function specifications) | |
140 | .TP | |
141 | .B \&.BR | |
142 | Bold alternating with Roman | |
143 | (especially useful for referring to other | |
144 | manual pages) | |
145 | .TP | |
146 | .B \&.I | |
147 | Italics | |
148 | .TP | |
149 | .B \&.IB | |
150 | Italics alternating with bold | |
151 | .TP | |
152 | .B \&.IR | |
153 | Italics alternating with Roman | |
154 | .TP | |
155 | .B \&.RB | |
156 | Roman alternating with bold | |
157 | .TP | |
158 | .B \&.RI | |
159 | Roman alternating with italics | |
160 | .TP | |
161 | .B \&.SB | |
162 | Small alternating with bold | |
163 | .TP | |
164 | .B \&.SM | |
165 | Small (useful for acronyms) | |
166 | .LP | |
167 | Traditionally, each command can have up to six arguments, but the GNU | |
168 | implementation removes this limitation (you might still want to limit | |
169 | yourself to 6 arguments for portability's sake). | |
c13182ef MK |
170 | Arguments are delimited by spaces. |
171 | Double quotes can be used to specify an argument which contains spaces. | |
172 | All of the arguments will be printed next to each other without | |
fea681da MK |
173 | intervening spaces, so that the |
174 | .B \&.BR | |
175 | command can be used to specify a word in bold followed by a mark of | |
176 | punctuation in Roman. | |
177 | If no arguments are given, the command is applied to the following line | |
178 | of text. | |
73d8cece | 179 | .SS Other macros and strings |
fea681da MK |
180 | .PP |
181 | Below are other relevant macros and predefined strings. | |
182 | Unless noted otherwise, all macros | |
183 | cause a break (end the current line of text). | |
184 | Many of these macros set or use the "prevailing indent." | |
185 | The "prevailing indent" value is set by any macro with the parameter | |
186 | .I i | |
187 | below; | |
188 | macros may omit | |
189 | .I i | |
190 | in which case the current prevailing indent will be used. | |
191 | As a result, successive indented paragraphs can use the same indent without | |
3b777aff | 192 | respecifying the indent value. |
24b74457 | 193 | A normal (nonindented) paragraph resets the prevailing indent value |
fea681da | 194 | to its default value (0.5 inches). |
f34cce68 | 195 | By default, a given indent is measured in ens; |
75fa8557 | 196 | try to use ens or ems as units for |
fea681da MK |
197 | indents, since these will automatically adjust to font size changes. |
198 | The other key macro definitions are: | |
73d8cece | 199 | .SS Normal paragraphs |
fea681da MK |
200 | .TP 9m |
201 | .B \&.LP | |
202 | Same as | |
203 | .B \&.PP | |
204 | (begin a new paragraph). | |
205 | .TP | |
206 | .B \&.P | |
207 | Same as | |
208 | .B \&.PP | |
209 | (begin a new paragraph). | |
210 | .TP | |
211 | .B \&.PP | |
212 | Begin a new paragraph and reset prevailing indent. | |
73d8cece | 213 | .SS Relative margin indent |
fea681da MK |
214 | .TP 9m |
215 | .BI \&.RS " i" | |
4d9b6984 | 216 | Start relative margin indent: moves the left margin |
fea681da MK |
217 | .I i |
218 | to the right (if | |
219 | .I i | |
220 | is omitted, the prevailing indent value is used). | |
221 | A new prevailing indent is set to 0.5 inches. | |
222 | As a result, all following paragraph(s) will be | |
223 | indented until the corresponding | |
224 | .BR \&.RE . | |
225 | .TP | |
226 | .B \&.RE | |
227 | End relative margin indent and | |
228 | restores the previous value of the prevailing indent. | |
73d8cece | 229 | .SS Indented paragraph macros |
fea681da MK |
230 | .TP 9m |
231 | .BI \&.HP " i" | |
232 | Begin paragraph with a hanging indent | |
233 | (the first line of the paragraph is at the left margin of | |
234 | normal paragraphs, and the rest of the paragraph's lines are indented). | |
235 | .TP | |
236 | .BI \&.IP " x i" | |
237 | Indented paragraph with optional hanging tag. | |
238 | If the tag | |
239 | .I x | |
240 | is omitted, the entire following paragraph is indented by | |
241 | .IR i . | |
242 | If the tag | |
243 | .I x | |
244 | is provided, it is hung at the left margin | |
245 | before the following indented paragraph | |
246 | (this is just like | |
0daa9e92 | 247 | .B \&.TP |
fea681da MK |
248 | except the tag is included with the command instead of being on the |
249 | following line). | |
250 | If the tag is too long, the text after the tag will be moved down to the | |
251 | next line (text will not be lost or garbled). | |
31a6818e | 252 | For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash) |
fea681da MK |
253 | as the tag, and for numbered lists, use the number or letter followed by |
254 | a period as the tag; | |
255 | this simplifies translation to other formats. | |
256 | .TP | |
257 | .BI \&.TP " i" | |
c13182ef MK |
258 | Begin paragraph with hanging tag. |
259 | The tag is given on the next line, but | |
fea681da MK |
260 | its results are like those of the |
261 | .B \&.IP | |
262 | command. | |
73d8cece | 263 | .SS Hypertext link macros |
dd1b9170 MK |
264 | (Feature supported with |
265 | .B groff | |
266 | only.) | |
fea681da MK |
267 | In order to use hypertext link macros, it is necessary to load the |
268 | .B www.tmac | |
269 | macro package. | |
270 | Use the request | |
271 | .B .mso www.tmac | |
272 | to do this. | |
273 | .TP 9m | |
274 | .BI \&.URL " url link trailer" | |
275 | Inserts a hypertext link to the URI (URL) | |
276 | .IR url , | |
277 | with | |
278 | .I link | |
279 | as the text of the link. | |
280 | The | |
281 | .I trailer | |
5fab2e7c | 282 | will be printed immediately afterward. |
fea681da MK |
283 | When generating HTML this should translate into the HTML command |
284 | \fB<A HREF="\fP\fIurl\fP\fB">\fIlink\fP\fB</A>\fP\fItrailer\fP. | |
285 | .\" The following is a kludge to get a paragraph into the listing. | |
286 | .TP | |
287 | .B " " | |
288 | This and other related macros are new, and | |
289 | many tools won't do anything with them, but | |
290 | since many tools (including troff) will simply ignore undefined macros | |
291 | (or at worst insert their text) these are safe to insert. | |
dd1b9170 MK |
292 | .\" The following is a kludge to get a paragraph into the listing. |
293 | .TP | |
294 | .B " " | |
295 | It can be useful to define your own | |
296 | .B URL | |
297 | macro in manual pages for the benefit of those viewing it with a roff | |
298 | viewer other than | |
299 | .BR groff . | |
300 | That way, the URL, link text, and trailer text (if any) are still visible. | |
301 | .\" The following is a kludge to get a paragraph into the listing. | |
302 | .TP | |
303 | .B " " | |
304 | Here's an example: | |
305 | .RS 1.5i | |
306 | \&.de URL | |
307 | .br | |
308 | \\\\$2 \\(laURL: \\\\$1 \\(ra\\\\$3 | |
309 | .br | |
310 | \&.. | |
311 | .br | |
312 | \&.if \\n[.g] .mso www.tmac | |
313 | .br | |
314 | \&.TH | |
315 | .I ... | |
316 | .br | |
317 | .I (later in the page) | |
318 | .br | |
319 | This software comes from the | |
320 | .br | |
321 | \&.URL "http://www.gnu.org/" "GNU Project" " of the" | |
322 | .br | |
323 | \&.URL "http://www.fsf.org/" "Free Software Foundation" . | |
324 | .RE | |
325 | .\" The following is a kludge to get a paragraph into the listing. | |
326 | .TP | |
327 | .B " " | |
328 | In the above, if | |
329 | .B groff | |
330 | is being used, the | |
331 | .B www.tmac | |
332 | macro package's definition of the URL macro will supersede the locally | |
333 | defined one. | |
fea681da | 334 | .PP |
c13182ef MK |
335 | A number of other link macros are available. |
336 | See | |
fea681da MK |
337 | .BR groff_www (7) |
338 | for more details. | |
73d8cece | 339 | .SS Miscellaneous macros |
fea681da MK |
340 | .TP 9m |
341 | .B \&.DT | |
342 | Reset tabs to default tab values (every 0.5 inches); | |
343 | does not cause a break. | |
344 | .TP | |
345 | .BI \&.PD " d" | |
346 | Set inter-paragraph vertical distance to d | |
347 | (if omitted, d=0.4v); | |
348 | does not cause a break. | |
349 | .TP | |
350 | .BI \&.SS " t" | |
351 | Subheading | |
352 | .I t | |
353 | (like | |
354 | .BR \&.SH , | |
355 | but used for a subsection inside a section). | |
73d8cece | 356 | .SS Predefined strings |
fea681da MK |
357 | The |
358 | .B man | |
359 | package has the following predefined strings: | |
31a6818e | 360 | .IP \e*R |
fea681da | 361 | Registration Symbol: \*R |
31a6818e | 362 | .IP \e*S |
fea681da | 363 | Change to default font size |
31a6818e | 364 | .IP \e*(Tm |
fea681da | 365 | Trademark Symbol: \*(Tm |
31a6818e | 366 | .IP \e*(lq |
eb1af896 | 367 | Left angled double quote: \*(lq |
31a6818e | 368 | .IP \e*(rq |
eb1af896 | 369 | Right angled double quote: \*(rq |
73d8cece | 370 | .SS Safe subset |
fea681da MK |
371 | Although technically |
372 | .B man | |
373 | is a troff macro package, in reality a large number of other tools | |
374 | process man page files that don't implement all of troff's abilities. | |
91749c0c MK |
375 | Thus, it's best to avoid some of troff's more exotic abilities |
376 | where possible to permit these other tools to work correctly. | |
fea681da MK |
377 | Avoid using the various troff preprocessors |
378 | (if you must, go ahead and use | |
379 | .BR tbl (1), | |
380 | but try to use the | |
381 | .B IP | |
c13182ef | 382 | and |
fea681da MK |
383 | .B TP |
384 | commands instead for two-column tables). | |
385 | Avoid using computations; most other tools can't process them. | |
386 | Use simple commands that are easy to translate to other formats. | |
387 | The following troff macros are believed to be safe (though in many cases | |
388 | they will be ignored by translators): | |
31a6818e | 389 | .BR \e" , |
fea681da MK |
390 | .BR . , |
391 | .BR ad , | |
392 | .BR bp , | |
393 | .BR br , | |
394 | .BR ce , | |
395 | .BR de , | |
396 | .BR ds , | |
397 | .BR el , | |
398 | .BR ie , | |
399 | .BR if , | |
400 | .BR fi , | |
401 | .BR ft , | |
402 | .BR hy , | |
403 | .BR ig , | |
404 | .BR in , | |
405 | .BR na , | |
406 | .BR ne , | |
407 | .BR nf , | |
408 | .BR nh , | |
409 | .BR ps , | |
410 | .BR so , | |
411 | .BR sp , | |
412 | .BR ti , | |
413 | .BR tr . | |
414 | .PP | |
415 | You may also use many troff escape sequences (those sequences beginning | |
31a6818e | 416 | with \e). |
fea681da | 417 | When you need to include the backslash character as normal text, |
31a6818e | 418 | use \ee. |
fea681da MK |
419 | Other sequences you may use, where x or xx are any characters and N |
420 | is any digit, include: | |
31a6818e MK |
421 | .BR \e' , |
422 | .BR \e` , | |
423 | .BR \e- , | |
424 | .BR \e. , | |
425 | .BR \e" , | |
426 | .BR \e% , | |
427 | .BR \e*x , | |
428 | .BR \e*(xx , | |
429 | .BR \e(xx , | |
430 | .BR \e$N , | |
431 | .BR \enx , | |
432 | .BR \en(xx , | |
433 | .BR \efx , | |
fea681da | 434 | and |
31a6818e | 435 | .BR \ef(xx . |
fea681da MK |
436 | Avoid using the escape sequences for drawing graphics. |
437 | .PP | |
438 | Do not use the optional parameter for | |
439 | .B bp | |
440 | (break page). | |
441 | Use only positive values for | |
442 | .B sp | |
443 | (vertical space). | |
444 | Don't define a macro | |
445 | .RB ( de ) | |
446 | with the same name as a macro in this or the | |
447 | mdoc macro package with a different meaning; it's likely that | |
448 | such redefinitions will be ignored. | |
449 | Every positive indent | |
450 | .RB ( in ) | |
451 | should be paired with a matching negative indent | |
452 | (although you should be using the | |
453 | .B RS | |
454 | and | |
455 | .B RE | |
456 | macros instead). | |
457 | The condition test | |
458 | .RB ( if,ie ) | |
9708eb37 | 459 | should only have \(aqt\(aq or \(aqn\(aq as the condition. |
c13182ef | 460 | Only translations |
fea681da MK |
461 | .RB ( tr ) |
462 | that can be ignored should be used. | |
463 | Font changes | |
464 | .RB ( ft | |
31a6818e | 465 | and the \fB\ef\fP escape sequence) |
fea681da MK |
466 | should only have the values 1, 2, 3, 4, R, I, B, P, or CW |
467 | (the ft command may also have no parameters). | |
468 | .PP | |
469 | If you use capabilities beyond these, check the | |
470 | results carefully on several tools. | |
471 | Once you've confirmed that the additional capability is safe, | |
472 | let the maintainer of this | |
473 | document know about the safe command or sequence | |
474 | that should be added to this list. | |
2b2581ee | 475 | .SH FILES |
add00eab | 476 | .IR /usr/share/groff/ [*/] tmac/an.tmac |
2b2581ee MK |
477 | .br |
478 | .I /usr/man/whatis | |
fea681da MK |
479 | .SH NOTES |
480 | .PP | |
481 | By all means include full URLs (or URIs) in the text itself; | |
482 | some tools such as | |
483 | .BR man2html (1) | |
484 | can automatically turn them into hypertext links. | |
485 | You can also use the new | |
486 | .B URL | |
487 | macro to identify links to related information. | |
488 | If you include URLs, use the full URL | |
608bf950 SK |
489 | (e.g., |
490 | .UR http://www.kernelnotes.org | |
491 | .UE ) | |
492 | to ensure that tools can automatically find the URLs. | |
fea681da MK |
493 | .PP |
494 | Tools processing these files should open the file and examine the first | |
24b74457 | 495 | nonwhitespace character. |
91749c0c MK |
496 | A period (.) or single quote (') at the beginning |
497 | of a line indicates a troff-based file (such as man or mdoc). | |
fea681da | 498 | A left angle bracket (<) indicates an SGML/XML-based |
c13182ef MK |
499 | file (such as HTML or Docbook). |
500 | Anything else suggests simple ASCII | |
fea681da MK |
501 | text (e.g., a "catman" result). |
502 | .PP | |
31a6818e | 503 | Many man pages begin with \fB\'\e"\fP followed by a |
91749c0c | 504 | space and a list of characters, |
fea681da | 505 | indicating how the page is to be preprocessed. |
91749c0c MK |
506 | For portability's sake to non-troff translators we recommend |
507 | that you avoid using anything other than | |
fea681da MK |
508 | .BR tbl (1), |
509 | and Linux can detect that automatically. | |
510 | However, you might want to include this information so your man page | |
511 | can be handled by other (less capable) systems. | |
512 | Here are the definitions of the preprocessors invoked by these characters: | |
513 | .TP 3 | |
514 | .B e | |
515 | eqn(1) | |
516 | .TP | |
517 | .B g | |
518 | grap(1) | |
519 | .TP | |
520 | .B p | |
521 | pic(1) | |
522 | .TP | |
523 | .B r | |
524 | refer(1) | |
525 | .TP | |
526 | .B t | |
527 | tbl(1) | |
528 | .TP | |
529 | .B v | |
530 | vgrind(1) | |
fea681da MK |
531 | .SH BUGS |
532 | .PP | |
533 | Most of the macros describe formatting (e.g., font type and spacing) instead | |
534 | of marking semantic content (e.g., this text is a reference to another page), | |
535 | compared to formats like mdoc and DocBook (even HTML has more semantic | |
536 | markings). | |
537 | This situation makes it harder to vary the | |
538 | .B man | |
539 | format for different media, | |
540 | to make the formatting consistent for a given media, and to automatically | |
541 | insert cross-references. | |
542 | By sticking to the safe subset described above, it should be easier to | |
543 | automate transitioning to a different reference page format in the future. | |
544 | .LP | |
545 | The Sun macro | |
546 | .B TX | |
547 | is not implemented. | |
fd7f0a7f MK |
548 | .\" .SH AUTHORS |
549 | .\" .IP \(em 3m | |
550 | .\" James Clark (jjc@jclark.com) wrote the implementation of the macro package. | |
551 | .\" .IP \(em | |
552 | .\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of | |
553 | .\" this manual page. | |
554 | .\" .IP \(em | |
555 | .\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO | |
556 | .\" (which influenced this manual page). | |
557 | .\" .IP \(em | |
558 | .\" David A. Wheeler (dwheeler@ida.org) heavily modified this | |
559 | .\" manual page, such as adding detailed information on sections and macros. | |
47297adb | 560 | .SH SEE ALSO |
fea681da MK |
561 | .BR apropos (1), |
562 | .BR groff (1), | |
a1712680 | 563 | .BR lexgrog (1), |
fea681da MK |
564 | .BR man (1), |
565 | .BR man2html (1), | |
e7cbacd4 | 566 | .BR whatis (1), |
d81dc982 | 567 | .BR groff_man (7), |
fea681da | 568 | .BR groff_www (7), |
e7cbacd4 MK |
569 | .BR man-pages (7), |
570 | .BR mdoc (7), | |
571 | .BR mdoc.samples (7) |