]>
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 | .\" | |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" | |
24 | .\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu) | |
25 | .\" Modified Sat Jun 8 00:39:52 1996 by aeb | |
26 | .\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org) | |
27 | .\" Modified Thu Jul 15 12:43:28 1999 by aeb | |
28 | .\" [todo: split this into man.7 describing the macros | |
29 | .\" and manpage.7 describing the Linux man page conventions] | |
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> | |
32 | .\" | |
33 | .TH MAN 7 2004-07-27 "Linux" "Linux Programmer's Manual" | |
34 | .SH NAME | |
35 | man \- macros to format man pages | |
36 | .SH SYNOPSIS | |
37 | .B groff \-Tascii \-man | |
38 | .I file | |
39 | \&... | |
40 | .LP | |
41 | .B groff \-Tps \-man | |
42 | .I file | |
43 | \&... | |
44 | .LP | |
45 | .B man | |
46 | .RI [ section ] | |
47 | .I title | |
48 | .SH DESCRIPTION | |
49 | This manual page explains the | |
50 | .B "groff tmac.an" | |
51 | macro package (often called the | |
52 | .B man | |
53 | macro package) and related conventions for creating manual (man) pages. | |
54 | This macro package should be used by developers when | |
c13182ef MK |
55 | writing or porting man pages for Linux. |
56 | It is fairly compatible with other | |
fea681da MK |
57 | versions of this macro package, so porting man pages should not be a major |
58 | problem (exceptions include the NET-2 BSD release, which uses a totally | |
59 | different macro package called mdoc; see | |
60 | .BR mdoc (7)). | |
61 | .PP | |
62 | Note that NET-2 BSD mdoc man pages can be used with | |
63 | .B groff | |
64 | simply by specifying the | |
65 | .B \-mdoc | |
66 | option instead of the | |
67 | .B \-man | |
c13182ef MK |
68 | option. |
69 | Using the | |
fea681da MK |
70 | .B \-mandoc |
71 | option is, however, recommended, since this will automatically detect which | |
72 | macro package is in use. | |
73 | .SH PREAMBLE | |
74 | The first command in a man page (after comment lines) should be | |
75 | .RS | |
76 | .sp | |
77 | .B \&.TH | |
78 | .IR "title section date source manual" , | |
79 | .sp | |
80 | .RE | |
81 | where: | |
82 | .RS | |
83 | .TP 10 | |
84 | .I title | |
85 | The title of the man page (e.g., | |
86 | .IR MAN ). | |
87 | .TP | |
88 | .I section | |
89 | The section number the man page should be placed in (e.g., | |
90 | .IR 7 ). | |
91 | .TP | |
92 | .I date | |
93 | The date of the last revision\(emremember to change this every time a | |
94 | change is made to the man page, since this is the most general way of doing | |
95 | version control. | |
96 | .TP | |
97 | .I source | |
98 | The source of the command. | |
99 | .sp | |
100 | For binaries, use something like: | |
101 | .IR GNU ", " NET-2 ", " "SLS Distribution" ", " "MCC Distribution" . | |
102 | .sp | |
103 | For system calls, use the version of the kernel that you are currently | |
104 | looking at: | |
105 | .IR "Linux 0.99.11" . | |
106 | .sp | |
107 | For library calls, use the source of the function: | |
b14d4aa5 | 108 | .IR GNU ", " "4.3BSD" ", " "Linux DLL 4.4.1" . |
fea681da MK |
109 | .TP |
110 | .I manual | |
111 | The title of the manual (e.g., | |
112 | .IR "Linux Programmer's Manual" ). | |
113 | .RE | |
114 | .PP | |
115 | Note that BSD mdoc-formatted pages begin with the | |
116 | .B Dd | |
117 | command, not the | |
118 | .B TH | |
119 | command. | |
120 | .PP | |
121 | The manual sections are traditionally defined as follows: | |
122 | .RS | |
123 | .TP 10 | |
124 | .B 1 Commands | |
125 | Those commands that can be executed by the user from within | |
126 | a shell. | |
127 | .TP | |
128 | .B 2 System calls | |
129 | Those functions which must be performed by the kernel. | |
130 | .TP | |
131 | .B 3 Library calls | |
132 | Most of the | |
133 | .I libc | |
134 | functions, such as | |
135 | .BR qsort (3). | |
136 | .TP | |
137 | .B 4 Special files | |
138 | Files found in | |
139 | .IR /dev . | |
140 | .TP | |
141 | .B 5 File formats and conventions | |
142 | The format for | |
143 | .I /etc/passwd | |
144 | and other human-readable files. | |
145 | .TP | |
146 | .B 6 Games | |
147 | .TP | |
148 | .B 7 Conventions and miscellaneous | |
149 | A description of the standard file system layout, network protocols, | |
150 | ASCII and other character codes, this man page, and other things. | |
151 | .TP | |
152 | .B 8 System management commands | |
153 | Commands like | |
154 | .BR mount (8), | |
155 | many of which only root can execute. | |
156 | .TP | |
157 | .B 9 Kernel routines | |
158 | This is an obsolete manual section. | |
159 | Once it was thought a good idea to document the Linux kernel here, | |
160 | but in fact very little has been documented, and the documentation | |
c13182ef MK |
161 | that exists is outdated already. |
162 | There are better sources of | |
163 | information for kernel developers. | |
fea681da MK |
164 | .RE |
165 | .SH SECTIONS | |
166 | Sections are started with | |
167 | .B \&.SH | |
c13182ef MK |
168 | followed by the heading name. |
169 | If the name contains spaces and appears | |
fea681da MK |
170 | on the same line as |
171 | .BR \&.SH , | |
c13182ef MK |
172 | then place the heading in double quotes. |
173 | Traditional or suggested | |
fea681da MK |
174 | headings include: |
175 | NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, | |
176 | EXIT STATUS, ERROR HANDLING, ERRORS, | |
177 | OPTIONS, USAGE, EXAMPLES, FILES, ENVIRONMENT, DIAGNOSTICS, SECURITY, | |
178 | CONFORMING TO, NOTES, BUGS, AUTHOR, and SEE ALSO. | |
179 | Where a traditional heading would apply, please use it; | |
180 | this kind of consistency can make the information easier to understand. | |
181 | However, feel free to create your own headings if they make things easier | |
182 | to understand. | |
183 | The only required heading is NAME, which should be the first section and | |
184 | be followed on the next line by a one line description of the program: | |
185 | .RS | |
186 | .sp | |
187 | \&.SH NAME | |
188 | .br | |
189 | chess \\- the game of chess | |
190 | .sp | |
191 | .RE | |
192 | It is extremely important that this format is followed, and that there is a | |
c13182ef MK |
193 | backslash before the single dash which follows the command name. |
194 | This syntax is used by the | |
fea681da MK |
195 | .BR makewhatis (8) |
196 | program to create a database of short command descriptions for the | |
197 | .BR whatis (1) | |
198 | and | |
199 | .BR apropos (1) | |
200 | commands. | |
201 | .PP | |
202 | Some other traditional sections have the following contents: | |
203 | .TP 14 | |
204 | .B SYNOPSIS | |
205 | briefly describes the command or function's interface. | |
206 | For commands, this shows the syntax of the command and its arguments | |
207 | (including options); | |
208 | boldface is used for as-is text and italics are used to indicate replaceable | |
c13182ef MK |
209 | arguments. |
210 | Brackets ([]) surround optional arguments, vertical bars (|) | |
fea681da MK |
211 | separate choices, and ellipses (\&...) can be repeated. |
212 | For functions, it shows any required data declarations or | |
213 | .B #include | |
214 | directives, followed by the function declaration. | |
215 | .TP | |
216 | .B DESCRIPTION | |
217 | gives an explanation of what the command, function, or format does. | |
218 | Discuss how it interacts with files and standard input, and what it | |
219 | produces on standard output or standard error. | |
220 | Omit internals and implementation details unless they're critical for | |
221 | understanding the interface. | |
222 | Describe the usual case; for information on options use the | |
223 | .B OPTIONS | |
224 | section. | |
225 | If there is some kind of input grammar or complex set of subcommands, | |
226 | consider describing them in a separate | |
227 | .B USAGE | |
228 | section (and just place an overview in the | |
229 | .B DESCRIPTION | |
230 | section). | |
231 | .TP | |
232 | .B RETURN VALUE | |
233 | gives a | |
234 | list of the values the library routine will return to the caller | |
235 | and the conditions that cause these values to be returned. | |
236 | .TP | |
237 | .B EXIT STATUS | |
238 | lists the possible exit status values or a program and | |
239 | the conditions that cause these values to be returned. | |
240 | .TP | |
241 | .B OPTIONS | |
242 | describes the options accepted by the program and how they change | |
243 | its behavior. | |
244 | .TP | |
245 | .B USAGE | |
246 | describes the grammar of any sublanguage this implements. | |
247 | .TP | |
248 | .B EXAMPLES | |
249 | provides one or more examples describing how this function, file or | |
250 | command is used. | |
251 | .TP | |
252 | .B FILES | |
253 | lists the files the program or function uses, such as | |
254 | configuration files, startup files, | |
255 | and files the program directly operates on. | |
256 | Give the full pathname of these files, and use the installation | |
257 | process to modify the directory part to match user preferences. | |
258 | For many programs, the default installation location is in | |
259 | .IR /usr/local , | |
260 | so your base manual page should use | |
261 | .I /usr/local | |
262 | as the base. | |
263 | .TP | |
264 | .B ENVIRONMENT | |
265 | lists all environment variables that affect your program or function | |
266 | and how they affect it. | |
267 | .TP | |
268 | .B DIAGNOSTICS | |
269 | gives an overview of the most common error messages and how to | |
c13182ef MK |
270 | cope with them. |
271 | You don't need to explain system error messages | |
fea681da MK |
272 | or fatal signals that can appear during execution of any program |
273 | unless they're special in some way to your program. | |
274 | .TP | |
275 | .B SECURITY | |
276 | discusses security issues and implications. | |
277 | Warn about configurations or environments that should be avoided, | |
278 | commands that may have security implications, and so on, especially | |
279 | if they aren't obvious. | |
280 | Discussing security in a separate section isn't necessary; | |
281 | if it's easier to understand, place security information in the | |
282 | other sections (such as the | |
283 | .B DESCRIPTION | |
284 | or | |
285 | .B USAGE | |
286 | section). | |
287 | However, please include security information somewhere! | |
288 | .TP | |
289 | .B CONFORMING TO | |
290 | describes any standards or conventions this implements. | |
291 | .TP | |
292 | .B NOTES | |
293 | provides miscellaneous notes. | |
294 | .TP | |
295 | .B BUGS | |
296 | lists limitations, known defects or inconveniences, | |
297 | and other questionable activities. | |
298 | .TP | |
299 | .B AUTHOR | |
300 | lists authors of the documentation or program so you can mail in bug | |
301 | reports. | |
302 | .TP | |
303 | .B SEE ALSO | |
304 | lists related man pages in alphabetical order, possibly followed by | |
305 | other related pages or documents. | |
306 | Conventionally this is the last section. | |
307 | .SH FONTS | |
308 | Although there are many arbitrary conventions for man pages in the UNIX | |
309 | world, the existence of several hundred Linux-specific man pages defines our | |
310 | font standards: | |
311 | .IP | |
312 | For functions, the arguments are always specified using italics, | |
313 | .IR "even in the SYNOPSIS section" , | |
314 | where the rest of the function is specified in bold: | |
315 | .RS | |
316 | .BI "int myfunction(int " argc ", char **" argv ); | |
317 | .RE | |
318 | .IP | |
319 | Filenames are always in italics (e.g., | |
320 | .IR "/usr/include/stdio.h" ), | |
321 | except in the SYNOPSIS section, where included files are in bold (e.g., | |
322 | .BR "#include <stdio.h>" ). | |
323 | .IP | |
324 | Special macros, which are usually in upper case, are in bold (e.g., | |
325 | .BR MAXINT ). | |
326 | .IP | |
327 | When enumerating a list of error codes, the codes are in bold (this list | |
328 | usually uses the | |
329 | .B \&.TP | |
330 | macro). | |
331 | .IP | |
332 | Any reference to another man page (or to the subject of the current man | |
c13182ef MK |
333 | page) is in bold. |
334 | If the manual section number is given, it is given in | |
fea681da MK |
335 | Roman (normal) font, without any spaces (e.g., |
336 | .BR man (7)). | |
337 | .LP | |
338 | The commands to select the type face are: | |
339 | .TP 4 | |
340 | .B \&.B | |
341 | Bold | |
342 | .TP | |
343 | .B \&.BI | |
344 | Bold alternating with italics | |
345 | (especially useful for function specifications) | |
346 | .TP | |
347 | .B \&.BR | |
348 | Bold alternating with Roman | |
349 | (especially useful for referring to other | |
350 | manual pages) | |
351 | .TP | |
352 | .B \&.I | |
353 | Italics | |
354 | .TP | |
355 | .B \&.IB | |
356 | Italics alternating with bold | |
357 | .TP | |
358 | .B \&.IR | |
359 | Italics alternating with Roman | |
360 | .TP | |
361 | .B \&.RB | |
362 | Roman alternating with bold | |
363 | .TP | |
364 | .B \&.RI | |
365 | Roman alternating with italics | |
366 | .TP | |
367 | .B \&.SB | |
368 | Small alternating with bold | |
369 | .TP | |
370 | .B \&.SM | |
371 | Small (useful for acronyms) | |
372 | .LP | |
373 | Traditionally, each command can have up to six arguments, but the GNU | |
374 | implementation removes this limitation (you might still want to limit | |
375 | yourself to 6 arguments for portability's sake). | |
c13182ef MK |
376 | Arguments are delimited by spaces. |
377 | Double quotes can be used to specify an argument which contains spaces. | |
378 | All of the arguments will be printed next to each other without | |
fea681da MK |
379 | intervening spaces, so that the |
380 | .B \&.BR | |
381 | command can be used to specify a word in bold followed by a mark of | |
382 | punctuation in Roman. | |
383 | If no arguments are given, the command is applied to the following line | |
384 | of text. | |
385 | .SH "OTHER MACROS AND STRINGS" | |
386 | .PP | |
387 | Below are other relevant macros and predefined strings. | |
388 | Unless noted otherwise, all macros | |
389 | cause a break (end the current line of text). | |
390 | Many of these macros set or use the "prevailing indent." | |
391 | The "prevailing indent" value is set by any macro with the parameter | |
392 | .I i | |
393 | below; | |
394 | macros may omit | |
395 | .I i | |
396 | in which case the current prevailing indent will be used. | |
397 | As a result, successive indented paragraphs can use the same indent without | |
398 | re-specifying the indent value. | |
399 | A normal (non-indented) paragraph resets the prevailing indent value | |
400 | to its default value (0.5 inches). | |
c13182ef | 401 | By default a given indent is measured in ens; |
75fa8557 | 402 | try to use ens or ems as units for |
fea681da MK |
403 | indents, since these will automatically adjust to font size changes. |
404 | The other key macro definitions are: | |
405 | .SS "Normal Paragraphs" | |
406 | .TP 9m | |
407 | .B \&.LP | |
408 | Same as | |
409 | .B \&.PP | |
410 | (begin a new paragraph). | |
411 | .TP | |
412 | .B \&.P | |
413 | Same as | |
414 | .B \&.PP | |
415 | (begin a new paragraph). | |
416 | .TP | |
417 | .B \&.PP | |
418 | Begin a new paragraph and reset prevailing indent. | |
419 | .SS "Relative Margin Indent" | |
420 | .TP 9m | |
421 | .BI \&.RS " i" | |
4d9b6984 | 422 | Start relative margin indent: moves the left margin |
fea681da MK |
423 | .I i |
424 | to the right (if | |
425 | .I i | |
426 | is omitted, the prevailing indent value is used). | |
427 | A new prevailing indent is set to 0.5 inches. | |
428 | As a result, all following paragraph(s) will be | |
429 | indented until the corresponding | |
430 | .BR \&.RE . | |
431 | .TP | |
432 | .B \&.RE | |
433 | End relative margin indent and | |
434 | restores the previous value of the prevailing indent. | |
435 | .SS "Indented Paragraph Macros" | |
436 | .TP 9m | |
437 | .BI \&.HP " i" | |
438 | Begin paragraph with a hanging indent | |
439 | (the first line of the paragraph is at the left margin of | |
440 | normal paragraphs, and the rest of the paragraph's lines are indented). | |
441 | .TP | |
442 | .BI \&.IP " x i" | |
443 | Indented paragraph with optional hanging tag. | |
444 | If the tag | |
445 | .I x | |
446 | is omitted, the entire following paragraph is indented by | |
447 | .IR i . | |
448 | If the tag | |
449 | .I x | |
450 | is provided, it is hung at the left margin | |
451 | before the following indented paragraph | |
452 | (this is just like | |
453 | .BR \&.TP | |
454 | except the tag is included with the command instead of being on the | |
455 | following line). | |
456 | If the tag is too long, the text after the tag will be moved down to the | |
457 | next line (text will not be lost or garbled). | |
458 | For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash) | |
459 | as the tag, and for numbered lists, use the number or letter followed by | |
460 | a period as the tag; | |
461 | this simplifies translation to other formats. | |
462 | .TP | |
463 | .BI \&.TP " i" | |
c13182ef MK |
464 | Begin paragraph with hanging tag. |
465 | The tag is given on the next line, but | |
fea681da MK |
466 | its results are like those of the |
467 | .B \&.IP | |
468 | command. | |
469 | .SS "Hypertext Link Macros" | |
dd1b9170 MK |
470 | (Feature supported with |
471 | .B groff | |
472 | only.) | |
fea681da MK |
473 | In order to use hypertext link macros, it is necessary to load the |
474 | .B www.tmac | |
475 | macro package. | |
476 | Use the request | |
477 | .B .mso www.tmac | |
478 | to do this. | |
479 | .TP 9m | |
480 | .BI \&.URL " url link trailer" | |
481 | Inserts a hypertext link to the URI (URL) | |
482 | .IR url , | |
483 | with | |
484 | .I link | |
485 | as the text of the link. | |
486 | The | |
487 | .I trailer | |
488 | will be printed immediately afterwards. | |
489 | When generating HTML this should translate into the HTML command | |
490 | \fB<A HREF="\fP\fIurl\fP\fB">\fIlink\fP\fB</A>\fP\fItrailer\fP. | |
491 | .\" The following is a kludge to get a paragraph into the listing. | |
492 | .TP | |
493 | .B " " | |
494 | This and other related macros are new, and | |
495 | many tools won't do anything with them, but | |
496 | since many tools (including troff) will simply ignore undefined macros | |
497 | (or at worst insert their text) these are safe to insert. | |
dd1b9170 MK |
498 | .\" The following is a kludge to get a paragraph into the listing. |
499 | .TP | |
500 | .B " " | |
501 | It can be useful to define your own | |
502 | .B URL | |
503 | macro in manual pages for the benefit of those viewing it with a roff | |
504 | viewer other than | |
505 | .BR groff . | |
506 | That way, the URL, link text, and trailer text (if any) are still visible. | |
507 | .\" The following is a kludge to get a paragraph into the listing. | |
508 | .TP | |
509 | .B " " | |
510 | Here's an example: | |
511 | .RS 1.5i | |
512 | \&.de URL | |
513 | .br | |
514 | \\\\$2 \\(laURL: \\\\$1 \\(ra\\\\$3 | |
515 | .br | |
516 | \&.. | |
517 | .br | |
518 | \&.if \\n[.g] .mso www.tmac | |
519 | .br | |
520 | \&.TH | |
521 | .I ... | |
522 | .br | |
523 | .I (later in the page) | |
524 | .br | |
525 | This software comes from the | |
526 | .br | |
527 | \&.URL "http://www.gnu.org/" "GNU Project" " of the" | |
528 | .br | |
529 | \&.URL "http://www.fsf.org/" "Free Software Foundation" . | |
530 | .RE | |
531 | .\" The following is a kludge to get a paragraph into the listing. | |
532 | .TP | |
533 | .B " " | |
534 | In the above, if | |
535 | .B groff | |
536 | is being used, the | |
537 | .B www.tmac | |
538 | macro package's definition of the URL macro will supersede the locally | |
539 | defined one. | |
fea681da | 540 | .PP |
c13182ef MK |
541 | A number of other link macros are available. |
542 | See | |
fea681da MK |
543 | .BR groff_www (7) |
544 | for more details. | |
545 | .SS "Miscellaneous Macros" | |
546 | .TP 9m | |
547 | .B \&.DT | |
548 | Reset tabs to default tab values (every 0.5 inches); | |
549 | does not cause a break. | |
550 | .TP | |
551 | .BI \&.PD " d" | |
552 | Set inter-paragraph vertical distance to d | |
553 | (if omitted, d=0.4v); | |
554 | does not cause a break. | |
555 | .TP | |
556 | .BI \&.SS " t" | |
557 | Subheading | |
558 | .I t | |
559 | (like | |
560 | .BR \&.SH , | |
561 | but used for a subsection inside a section). | |
562 | .SS "Predefined Strings" | |
563 | The | |
564 | .B man | |
565 | package has the following predefined strings: | |
566 | .IP \e*R | |
567 | Registration Symbol: \*R | |
568 | .IP \e*S | |
569 | Change to default font size | |
570 | .IP \e*(Tm | |
571 | Trademark Symbol: \*(Tm | |
572 | .IP \e*(lq | |
573 | Left angled doublequote: \*(lq | |
574 | .IP \e*(rq | |
575 | Right angled doublequote: \*(rq | |
576 | .SH "SAFE SUBSET" | |
577 | Although technically | |
578 | .B man | |
579 | is a troff macro package, in reality a large number of other tools | |
580 | process man page files that don't implement all of troff's abilities. | |
581 | Thus, it's best to avoid some of troff's more exotic abilities where possible | |
582 | to permit these other tools to work correctly. | |
583 | Avoid using the various troff preprocessors | |
584 | (if you must, go ahead and use | |
585 | .BR tbl (1), | |
586 | but try to use the | |
587 | .B IP | |
c13182ef | 588 | and |
fea681da MK |
589 | .B TP |
590 | commands instead for two-column tables). | |
591 | Avoid using computations; most other tools can't process them. | |
592 | Use simple commands that are easy to translate to other formats. | |
593 | The following troff macros are believed to be safe (though in many cases | |
594 | they will be ignored by translators): | |
595 | .BR \e" , | |
596 | .BR . , | |
597 | .BR ad , | |
598 | .BR bp , | |
599 | .BR br , | |
600 | .BR ce , | |
601 | .BR de , | |
602 | .BR ds , | |
603 | .BR el , | |
604 | .BR ie , | |
605 | .BR if , | |
606 | .BR fi , | |
607 | .BR ft , | |
608 | .BR hy , | |
609 | .BR ig , | |
610 | .BR in , | |
611 | .BR na , | |
612 | .BR ne , | |
613 | .BR nf , | |
614 | .BR nh , | |
615 | .BR ps , | |
616 | .BR so , | |
617 | .BR sp , | |
618 | .BR ti , | |
619 | .BR tr . | |
620 | .PP | |
621 | You may also use many troff escape sequences (those sequences beginning | |
622 | with \e). | |
623 | When you need to include the backslash character as normal text, | |
624 | use \ee. | |
625 | Other sequences you may use, where x or xx are any characters and N | |
626 | is any digit, include: | |
627 | .BR \e' , | |
628 | .BR \e` , | |
629 | .BR \e- , | |
630 | .BR \e. , | |
631 | .BR \e" , | |
632 | .BR \e% , | |
633 | .BR \e*x , | |
634 | .BR \e*(xx , | |
635 | .BR \e(xx , | |
636 | .BR \e$N , | |
637 | .BR \enx , | |
638 | .BR \en(xx , | |
639 | .BR \efx , | |
640 | and | |
641 | .BR \ef(xx . | |
642 | Avoid using the escape sequences for drawing graphics. | |
643 | .PP | |
644 | Do not use the optional parameter for | |
645 | .B bp | |
646 | (break page). | |
647 | Use only positive values for | |
648 | .B sp | |
649 | (vertical space). | |
650 | Don't define a macro | |
651 | .RB ( de ) | |
652 | with the same name as a macro in this or the | |
653 | mdoc macro package with a different meaning; it's likely that | |
654 | such redefinitions will be ignored. | |
655 | Every positive indent | |
656 | .RB ( in ) | |
657 | should be paired with a matching negative indent | |
658 | (although you should be using the | |
659 | .B RS | |
660 | and | |
661 | .B RE | |
662 | macros instead). | |
663 | The condition test | |
664 | .RB ( if,ie ) | |
665 | should only have 't' or 'n' as the condition. | |
c13182ef | 666 | Only translations |
fea681da MK |
667 | .RB ( tr ) |
668 | that can be ignored should be used. | |
669 | Font changes | |
670 | .RB ( ft | |
671 | and the \fB\ef\fP escape sequence) | |
672 | should only have the values 1, 2, 3, 4, R, I, B, P, or CW | |
673 | (the ft command may also have no parameters). | |
674 | .PP | |
675 | If you use capabilities beyond these, check the | |
676 | results carefully on several tools. | |
677 | Once you've confirmed that the additional capability is safe, | |
678 | let the maintainer of this | |
679 | document know about the safe command or sequence | |
680 | that should be added to this list. | |
681 | .SH NOTES | |
682 | .PP | |
683 | By all means include full URLs (or URIs) in the text itself; | |
684 | some tools such as | |
685 | .BR man2html (1) | |
686 | can automatically turn them into hypertext links. | |
687 | You can also use the new | |
688 | .B URL | |
689 | macro to identify links to related information. | |
690 | If you include URLs, use the full URL | |
691 | (e.g., <http://www.kernelnotes.org>) to ensure that tools | |
692 | can automatically find the URLs. | |
693 | .PP | |
694 | Tools processing these files should open the file and examine the first | |
c13182ef MK |
695 | non-whitespace character. |
696 | A period (.) or single quote (') | |
fea681da MK |
697 | at the beginning of a line indicates a troff-based file (such as man or mdoc). |
698 | A left angle bracket (<) indicates an SGML/XML-based | |
c13182ef MK |
699 | file (such as HTML or Docbook). |
700 | Anything else suggests simple ASCII | |
fea681da MK |
701 | text (e.g., a "catman" result). |
702 | .PP | |
703 | Many man pages begin with '\e" followed by a space and a list of characters, | |
704 | indicating how the page is to be preprocessed. | |
705 | For portability's sake to non-troff translators we recommend that you avoid | |
706 | using anything other than | |
707 | .BR tbl (1), | |
708 | and Linux can detect that automatically. | |
709 | However, you might want to include this information so your man page | |
710 | can be handled by other (less capable) systems. | |
711 | Here are the definitions of the preprocessors invoked by these characters: | |
712 | .TP 3 | |
713 | .B e | |
714 | eqn(1) | |
715 | .TP | |
716 | .B g | |
717 | grap(1) | |
718 | .TP | |
719 | .B p | |
720 | pic(1) | |
721 | .TP | |
722 | .B r | |
723 | refer(1) | |
724 | .TP | |
725 | .B t | |
726 | tbl(1) | |
727 | .TP | |
728 | .B v | |
729 | vgrind(1) | |
730 | .SH FILES | |
731 | .IR /usr/share/groff/ [*/] tmac/tmac.an | |
732 | .br | |
733 | .I /usr/man/whatis | |
734 | .SH BUGS | |
735 | .PP | |
736 | Most of the macros describe formatting (e.g., font type and spacing) instead | |
737 | of marking semantic content (e.g., this text is a reference to another page), | |
738 | compared to formats like mdoc and DocBook (even HTML has more semantic | |
739 | markings). | |
740 | This situation makes it harder to vary the | |
741 | .B man | |
742 | format for different media, | |
743 | to make the formatting consistent for a given media, and to automatically | |
744 | insert cross-references. | |
745 | By sticking to the safe subset described above, it should be easier to | |
746 | automate transitioning to a different reference page format in the future. | |
747 | .LP | |
748 | The Sun macro | |
749 | .B TX | |
750 | is not implemented. | |
751 | .SH AUTHORS | |
752 | .IP \(em 3m | |
753 | James Clark (jjc@jclark.com) wrote the implementation of the macro package. | |
754 | .IP \(em | |
755 | Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of | |
756 | this manual page. | |
757 | .IP \(em | |
758 | Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO | |
759 | (which influenced this manual page). | |
760 | .IP \(em | |
761 | David A. Wheeler (dwheeler@ida.org) heavily modified this | |
762 | manual page, such as adding detailed information on sections and macros. | |
763 | .SH "SEE ALSO" | |
764 | .BR apropos (1), | |
765 | .BR groff (1), | |
766 | .BR man (1), | |
767 | .BR man2html (1), | |
768 | .BR mdoc (7), | |
769 | .BR mdoc.samples (7), | |
d81dc982 | 770 | .BR groff_man (7), |
fea681da MK |
771 | .BR groff_www (7), |
772 | .BR whatis (1) |