Penguin
Recent Changes
Annotated edit history of man(7) version 4, including all changes. View license author blame.
Rev Author # Line
2 perry 1 MAN
2 !!!MAN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 PREAMBLE
7 SECTIONS
8 FONTS
9 OTHER MACROS AND STRINGS
10 SAFE SUBSET
11 NOTES
12 FILES
13 BUGS
14 AUTHORS
15 SEE ALSO
16 ----
17 !!NAME
18
19
20 man - macros to format man pages
21 !!SYNOPSIS
22
23
24 __groff -Tascii -man__ ''file'' ...
25
26
27 __groff -Tps -man__ ''file'' ...
28
29
30 __man__ [[''section''] ''title''
31 !!DESCRIPTION
32
33
34 This manual page explains the __groff tmac.an__ macro
35 package (often called the __man__ macro package) and
36 related conventions for creating manual (man) pages. This
37 macro package should be used by developers when writing or
38 porting man pages for Linux. It is fairly compatible with
39 other versions of this macro package, so porting man pages
40 should not be a major problem (exceptions include the NET-2
41 BSD release, which uses a totally different macro package
42 called mdoc; see mdoc(7)).
43
44
45 Note that NET-2 BSD mdoc man pages can be used with
46 __groff__ simply by specifying the __-mdoc__ option
47 instead of the __-man__ option. Using the __-mandoc__
48 option is, however, recommended, since this will
49 automatically detect which macro package is in
50 use.
51 !!PREAMBLE
52
53
54 The first command in a man page (after comment lines) should
55 be
56
57
58 __.TH__ ''title section date source
59 manual'',
60
61
62 where:
63
64
65 ''title''
66
67
68 The title of the man page (e.g., ''MAN'').
69
70
71 ''section''
72
73
74 The section number the man page should be placed in (e.g.,
75 ''7'').
76
77
78 ''date''
79
80
81 The date of the last revision--remember to change this every
82 time a change is made to the man page, since this is the
83 most general way of doing version control.
84
85
86 ''source''
87
88
89 The source of the command.
90
91
92 For binaries, use something like: ''GNU'', ''NET-2'',
93 ''SLS Distribution'', ''MCC
94 Distribution''.
95
96
97 For system calls, use the version of the kernel that you are
98 currently looking at: ''Linux 0.99.11''.
99
100
101 For library calls, use the source of the function:
102 ''GNU'', ''BSD 4.3'', ''Linux DLL
103 4.4.1''.
104
105
106 ''manual''
107
108
109 The title of the manual (e.g., ''Linux Programmer's
110 Manual'').
111
112
113 Note that BSD mdoc-formatted pages begin with the __Dd__
114 command, not the __TH__ command.
115
116
117 The manual sections are traditionally defined as
118 follows:
119
120
121 __1 Commands__
122
123
124 Those commands that can be executed by the user from within
125 a shell.
126
127
128 __2 System calls__
129
130
131 Those functions which must be performed by the
132 kernel.
133
134
135 __3 Library calls__
136
137
138 Most of the ''libc'' functions, such as
139 qsort(3))
140
141
142 __4 Special files__
143
144
145 Files found in ''/dev'')
146
147
148 __5 File formats and conventions__
149
150
151 The format for ''/etc/passwd'' and other human-readable
152 files.
153
154
155 __6 Games__
156
157
158 __7 Macro packages and conventions__
159
160
161 A description of the standard file system layout, network
162 protocols, ASCII and other character codes, this man page,
163 and other things.
164
165
166 __8 System management commands__
167
168
169 Commands like mount(8), many of which only
170 ''root'' can execute.
171
172
173 __9 Kernel routines__
174
175
176 This is an obsolete manual section. Once it was thought a
177 good idea to document the Linux kernel here, but in fact
178 very little has been documented, and the documentation that
179 exists is outdated already. There are better sources of
180 information for kernel developers.
181 !!SECTIONS
182
183
184 Sections are started with __.SH__ followed by the heading
185 name. If the name contains spaces and appears on the same
186 line as __.SH__, then place the heading in double quotes.
187 Traditional or suggested headings include: NAME, SYNOPSIS,
188 DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR HANDLING,
189 ERRORS, OPTIONS, USAGE, FILES, ENVIRONMENT, DIAGNOSTICS,
190 SECURITY, CONFORMING TO, NOTES, BUGS, AUTHOR, and SEE ALSO.
191 Where a traditional heading would apply, please use it; this
192 kind of consistency can make the information easier to
193 understand. However, feel free to create your own headings
194 if they make things easier to understand. The only required
195 heading is ''NAME'', which should be the first section
196 and be followed on the next line by a one line description
197 of the program:
198
199
200 .SH NAME
201 chess - the game of chess
202
203
204 It is extremely important that this format is followed, and
205 that there is a backslash before the single dash which
206 follows the command name. This syntax is used by the
207 makewhatis(8) or mandb(8) programs to create a
208 database of short command descriptions for the
209 whatis(1) and apropos(1)
210 commands.
211
212
213 Some other traditional sections have the following
214 contents:
215
216
217 __SYNOPSIS__
218
219
220 briefly describes the command or function's interface. For
221 commands, this shows the syntax of the command and its
222 arguments (including options); boldface is used for as-is
223 text and italics are used to indicate replaceable arguments.
224 Brackets ([[]) surround optional arguments, vertical bars (|)
225 separate choices, and ellipses (...) can be repeated. For
226 functions, it shows any required data declarations or
227 __#include__ directives, followed by the function
228 declaration.
229
230
231 __DESCRIPTION__
232
233
234 gives an explanation of what the command, function, or
235 format does. Discuss how it interacts with files and
236 standard input, and what it produces on standard output or
237 standard error. Omit internals and implementation details
238 unless they're critical for understanding the interface.
239 Describe the usual case; for information on options use the
240 __OPTIONS__ section. If there is some kind of input
241 grammar or complex set of subcommands, consider describing
242 them in a separate __USAGE__ section (and just place an
243 overview in the __DESCRIPTION__ section).
244
245
246 __RETURN VALUE__
247
248
249 gives a list of the values the library routine will return
250 to the caller and the conditions that cause these values to
251 be returned.
252
253
254 __EXIT STATUS__
255
256
257 lists the possible exit status values or a program and the
258 conditions that cause these values to be
259 returned.
260
261
262 __OPTIONS__
263
264
265 describes the options accepted by the program and how they
266 change its behavior.
267
268
269 __USAGE__ describes the grammar of any sublanguage this
270 implements.
271
272
273 __FILES__ lists the files the program or function uses,
274 such as configuration files, startup files, and files the
275 program directly operates on. Give the full pathname of
276 these files, and use the installation process to modify the
277 directory part to match user preferences. For many programs,
278 the default installation location is in /usr/local, so your
279 base manual page should use /usr/local as the
280 base.
281
282
283 __ENVIRONMENT__
284
285
286 lists all environment variables that affect your program or
287 function and how they affect it.
288
289
290 __DIAGNOSTICS__
291
292
293 gives an overview of the most common error messages and how
294 to cope with them. You don't need to explain system error
295 messages or fatal signals that can appear during execution
296 of any program unless they're special in some way to your
297 program.
298
299
300 __SECURITY__
301
302
303 discusses security issues and implications. Warn about
304 configurations or environments that should be avoided,
305 commands that may have security implications, and so on,
306 especially if they aren't obvious. Discussing security in a
307 separate section isn't necessary; if it's easier to
308 understand, place security information in the other sections
309 (such as the __DESCRIPTION__ or __USAGE__ section).
310 However, please include security information
311 somewhere!
312
313
314 __CONFORMING TO__
315
316
317 describes any standards or conventions this
318 implements.
319
320
321 __NOTES__ provides miscellaneous notes.
322
323
324 __BUGS__ lists limitations, known defects or
325 inconveniences, and other questionable
326 activities.
327
328
329 __AUTHOR__ lists authors of the documentation or program
330 so you can mail in bug reports.
331
332
333 __SEE ALSO__
334
335
336 lists related man pages in alphabetical order, possibly
337 followed by other related pages or documents. Conventionally
338 this is the last section.
339 !!FONTS
340
341
342 Although there are many arbitrary conventions for man pages
343 in the UNIX world, the existence of several hundred
344 Linux-specific man pages defines our font
345 standards:
346
347
348 For functions, the arguments are always specified using
349 italics, ''even in the SYNOPSIS section'', where the rest
350 of the function is specified in bold:__
351 int myfunction(int__ ''argc''__, char
352 **__''argv''__);__
353
354
355 Filenames are always in italics (e.g.,
356 ''/usr/include/stdio.h''), except in the SYNOPSIS
357 section, where included files are in bold (e.g., __#include
358 __).
359
360
361 Special macros, which are usually in upper case, are in bold
362 (e.g., __MAXINT__).
363
364
365 When enumerating a list of error codes, the codes are in
366 bold (this list usually uses the __.TP__
367 macro).
368
369
370 Any reference to another man page (or to the subject of the
371 current man page) is in bold. If the manual section number
372 is given, it is given in Roman (normal) font, without any
373 spaces (e.g., man(7)).
374
375
376 The commands to select the type face are:
377
378
379 __.B__
380
381
382 Bold
383
384
385 __.BI__
386
387
388 Bold alternating with italics (especially useful for
389 function specifications)
390
391
392 __.BR__
393
394
395 Bold alternating with Roman (especially useful for referring
396 to other manual pages)
397
398
399 __.I__
400
401
402 Italics
403
404
405 __.IB__
406
407
408 Italics alternating with bold
409
410
411 __.IR__
412
413
414 Italics alternating with Roman
415
416
417 __.RB__
418
419
420 Roman alternating with bold
421
422
423 __.RI__
424
425
426 Roman alternating with italics
427
428
429 __.SB__
430
431
432 Small alternating with bold
433
434
435 __.SM__
436
437
438 Small (useful for acronyms)
439
440
441 Traditionally, each command can have up to six arguments,
442 but the GNU implementation removes this limitation (you
443 might still want to limit yourself to 6 arguments for
444 portability's sake). Arguments are delimited by spaces.
445 Double quotes can be used to specify an argument which
446 contains spaces. All of the arguments will be printed next
447 to each other without intervening spaces, so that the
448 __.BR__ command can be used to specify a word in bold
449 followed by a mark of punctuation in Roman. If no arguments
450 are given, the command is applied to the following line of
451 text.
452 !!OTHER MACROS AND STRINGS
453
454
455 Below are other relevant macros and predefined strings.
456 Unless noted otherwise, all macros cause a break (end the
457 current line of text). Many of these macros set or use the
458 i'' below; macros may omit ''i'' in which case the
459 current prevailing indent will be used. As a result,
460 successive indented paragraphs can use the same indent
461 without re-specifying the indent value. A normal
462 (non-indented) paragraph resets the prevailing indent value
463 to its default value (0.5 inches). By default a given indent
464 is measured in ens; try to ens or ems as units for indents,
465 since these will automatically adjust to font size changes.
466 The other key macro definitions are:
467
468
469 __Normal Paragraphs__
470
471
472 __.LP__
473
474
475 Same as __.PP__ (begin a new paragraph).
476
477
478 __.P__
479
480
481 Same as __.PP__ (begin a new paragraph).
482
483
484 __.PP__
485
486
487 Begin a new paragraph and reset prevailing
488 indent.
489
490
491 __Relative Margin Indent__
492
493
494 __.RS__ ''i''
495
496
497 Start relative margin indent - moves the left margin
498 ''i'' to the right (if ''i'' is omitted, the
499 prevailing indent value is used). A new prevailing indent is
500 set to 0.5 inches. As a result, all following paragraph(s)
501 will be indented until the corresponding
502 __.RE__.
503
504
505 __.RE__
506
507
508 End relative margin indent and restores the previous value
509 of the prevailing indent.
510
511
512 __Indented Paragraph Macros__
513
514
515 __.HP__ ''i''
516
517
518 Begin paragraph with a hanging indent (the first line of the
519 paragraph is at the left margin of normal paragraphs, and
520 the rest of the paragraph's lines are
521 indented).
522
523
524 __.IP__ ''x i''
525
526
527 Indented paragraph with optional hanging tag. If the tag
528 ''x'' is omitted, the entire following paragraph is
529 indented by ''i''. If the tag ''x'' is provided, it is
530 hung at the left margin before the following indented
531 paragraph (this is just like __.TP__ except the tag is
532 included with the command instead of being on the following
533 line). If the tag is too long, the text after the tag will
534 be moved down to the next line (text will not be lost or
535 garbled). For bulleted lists, use this macro with (bullet)
536 or (em dash) as the tag, and for numbered lists, use the
537 number or letter followed by a period as the tag; this
538 simplifies translation to other formats.
539
540
541 __.TP__ ''i''
542
543
544 Begin paragraph with hanging tag. The tag is given on the
545 next line, but its results are like those of the __.IP__
546 command.
547
548
549 __Hypertext Link Macros__
550
551
552 __.UR__ ''u''
553
554
555 Begins a hypertext link to the URI (URL) ''u''; it will
556 end with the corresponding __UE__ command. When
557 generating HTML this should translate into the HTML command
558 ____''u''____. There is
559 an exception: if ''u'' is the special value
560 ''UE__ (this permits
4 AristotlePagaltzis 561 disabling hypertext links in phrases like !LALR(1) when
2 perry 562 linking is not appropriate). These hypertext link
563 __
564
565
566 __.UE__
567
568
569 Ends the corresponding __UR__ command; when generating
570 HTML this should translate into
571 ____.
572
573
574 __.UN__ ''u''
575
576
577 Creates a named hypertext location named ''u''; do not
578 include a corresponding __UE__ command. When generating
579 HTML this should translate into the HTML command __
580 __''u''__
581 __''u''____
582 (the
583 __
584
585
586 __Miscellaneous Macros__
587
588
589 __.DT__
590
591
592 Reset tabs to default tab values (every 0.5 inches); does
593 not cause a break.
594
595
596 __.IX__ ''...''
597
598
599 Inserts index information (for a search system or printed
600 index list). Index information is not normally displayed in
601 the page itself. If followed by a single parameter, the
602 parameter is added as a standalone index term pointing to
603 this location in the man page. If it's two parameters, it's
604 probably in Perl manpage format; the first parameter
605 identifies the type of name (one of Name, Title, Header,
606 Subsection, or Item) and the second parameter the name
607 itself to be indexed. Otherwise, it's in the long index
608 format: each parameter gives an index term, subordinate
609 index term, subsubordinate index term, and so on until
610 terminated by an empty parameter, then a parameter with the
611 name of the program, em, and short description; this may be
612 followed by another empty parameter and possibly by page
613 control messages (e.g. PAGE START). An example of this would
614 be
615
616
617 __.PD__ ''d''
618
619
620 Set inter-paragraph vertical distance to d (if omitted,
621 d=0.4v); does not cause a break.
622
623
624 __.SS__ ''t''
625
626
627 Subheading ''t'' (like __.SH__, but used for a
628 subsection inside a section).
629
630
631 __Predefined Strings__
632
633
634 The __man__ package has the following predefined
635 strings:
636
637
638 *R
639
640
641 Registration Symbol:
642
643
644 *S
645
646
647 Change to default font size
648
649
650 *(Tm
651
652
653 Trademark Symbol: (TM)
654
655
656 *(lq
657
658
659 Left angled doublequote: ``
660
661
662 *(rq
663
664
665 Right angled doublequote: ''
666 !!SAFE SUBSET
667
668
669 Although technically __man__ is a troff macro package, in
670 reality a large number of other tools process man page files
671 that don't implement all of troff's abilities. Thus, it's
672 best to avoid some of troff's more exotic abilities where
673 possible to permit these other tools to work correctly.
674 Avoid using the various troff preprocessors (if you must, go
675 ahead and use tbl(1), but try to use the __IP__
676 and __TP__ commands instead for two-column tables). Avoid
677 using computations; most other tools can't process them. Use
678 simple commands that are easy to translate to other formats.
679 The following troff macros are believed to be safe (though
680 in many cases they will be ignored by translators):
681 ____, __.__, __ad__, __bp__, __br__,
682 __ce__, __de__, __ds__, __el__, __ie__,
683 __if__, __fi__, __ft__, __hy__, __ig__,
684 __in__, __na__, __ne__, __nf__, __nh__,
685 __ps__, __so__, __sp__, __ti__,
686 __tr__.
687
688
689 You may also use many troff escape sequences (those
690 sequences beginning with ). When you need to include the
691 backslash character as normal text, use e. Other sequences
692 you may use, where x or xx are any characters and N is any
693 digit, include: __'__, __`__, __-__, __.__,
694 ____, __%__, __*x__, __*(xx__, ____,
695 __$N__, __nx__, __n(xx__, __fx__, and
696 __f(xx__. Avoid using the escape sequences for drawing
697 graphics.
698
699
700 Do not use the optional parameter for __bp__ (break
701 page). Use only positive values for __sp__ (vertical
702 space). Don't define a macro (__de__) with the same name
703 as a macro in this or the mdoc macro package with a
704 different meaning; it's likely that such redefinitions will
705 be ignored. Every positive indent (__in__) should be
706 paired with a matching negative indent (although you should
707 be using the __RS__ and __RE__ macros instead). The
708 condition test (__if,ie__) should only have 't' or 'n' as
709 the condition. Only translations (__tr__) that can be
710 ignored should be used. Font changes (__ft__ and the
711 __f__ escape sequence) should only have the values 1, 2,
712 3, 4, R, I, B, P, or CW (the ft command may also have no
713 parameters).
714
715
716 If you use capabilities beyond these, check the results
717 carefully on several tools. Once you've confirmed that the
718 additional capability is safe, let the maintainer of this
719 document know about the safe command or sequence that should
720 be added to this list.
721 !!NOTES
722
723
724 By all means include full URLs (or URIs) in the text itself;
3 perry 725 some tools such as man2html(1) can automatically turn
2 perry 726 them into hypertext links. You can also use the new
727 __UR__ macro to identify links to related information. If
728 you include URLs, use the full URL (e.g.,
729 __
730
731
732 Tools processing these files should open the file and
733 examine the first non-whitespace character. A period (.) or
734 single quote (') at the beginning of a line indicates a
735 troff-based file (such as man or mdoc). A left angle bracket
736 (
737
738
739 Many man pages begin with '
740 tbl__(1), and Linux can detect that automatically.
741 However, you might want to include this information so your
742 man page can be handled by other (less capable) systems.
743 Here are the definitions of the preprocessors invoked by
744 these characters:
745
746
747 __e__
748
749
750 eqn(1)
751
752
753 __g__
754
755
756 grap(1)
757
758
759 __p__
760
761
762 pic(1)
763
764
765 __r__
766
767
768 refer(1)
769
770
771 __t__
772
773
774 tbl(1)
775
776
777 __v__
778
779
780 vgrind(1)
781 !!FILES
782
783
784 ''/usr/share/groff/tmac/tmac.an
785 /usr/man/whatis''
786 !!BUGS
787
788
789 Most of the macros describe formatting (e.g., font type and
790 spacing) instead of marking semantic content (e.g., this
791 text is a reference to another page), compared to formats
792 like mdoc and !DocBook (even HTML has more semantic
793 markings). This situation makes it harder to vary the
794 __man__ format for different media, to make the
795 formatting consistent for a given media, and to
796 automatically insert cross-references. By sticking to the
797 safe subset described above, it should be easier to automate
798 transitioning to a different reference page format in the
799 future.
800
801
802 The Sun macro __TX__ is not implemented.
803 !!AUTHORS
804
805
806 --
807
808
809 James Clark (jjc@jclark.com) wrote the implementation of the
810 macro package.
811
812
813 --
814
815
816 Rickard E. Faith (faith@cs.unc.edu) wrote the initial
817 version of this manual page.
818
819
820 --
821
822
823 Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux
824 Man-Page Mini-HOWTO (which influenced this manual
825 page).
826
827
828 --
829
830
831 David A. Wheeler (dwheeler@ida.org) heavily modified this
832 manual page, such as adding detailed information on sections
833 and macros.
834 !!SEE ALSO
835
836
837 apropos(1), groff(1), man(1),
3 perry 838 man2html(1), mdoc(7), __mdoc.samples__(7),
2 perry 839 whatis(1)
840 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.