diff options
Diffstat (limited to 'man7/man.7')
| -rw-r--r-- | man7/man.7 | 58 |
1 files changed, 35 insertions, 23 deletions
diff --git a/man7/man.7 b/man7/man.7 index e567e0fc62..e660fd3c0b 100644 --- a/man7/man.7 +++ b/man7/man.7 @@ -9,7 +9,7 @@ .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. -.\" +.\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from @@ -17,7 +17,7 @@ .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. -.\" +.\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" @@ -52,7 +52,8 @@ macro package (often called the .B man macro package) and related conventions for creating manual (man) pages. This macro package should be used by developers when -writing or porting man pages for Linux. It is fairly compatible with other +writing or porting man pages for Linux. +It is fairly compatible with other versions of this macro package, so porting man pages should not be a major problem (exceptions include the NET-2 BSD release, which uses a totally different macro package called mdoc; see @@ -64,7 +65,8 @@ simply by specifying the .B \-mdoc option instead of the .B \-man -option. Using the +option. +Using the .B \-mandoc option is, however, recommended, since this will automatically detect which macro package is in use. @@ -156,16 +158,19 @@ many of which only root can execute. This is an obsolete manual section. Once it was thought a good idea to document the Linux kernel here, but in fact very little has been documented, and the documentation -that exists is outdated already. There are better sources of -information for kernel developers. +that exists is outdated already. +There are better sources of +information for kernel developers. .RE .SH SECTIONS Sections are started with .B \&.SH -followed by the heading name. If the name contains spaces and appears +followed by the heading name. +If the name contains spaces and appears on the same line as .BR \&.SH , -then place the heading in double quotes. Traditional or suggested +then place the heading in double quotes. +Traditional or suggested headings include: NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR HANDLING, ERRORS, @@ -185,8 +190,8 @@ chess \\- the game of chess .sp .RE It is extremely important that this format is followed, and that there is a -backslash before the single dash which follows the command name. This -syntax is used by the +backslash before the single dash which follows the command name. +This syntax is used by the .BR makewhatis (8) program to create a database of short command descriptions for the .BR whatis (1) @@ -201,7 +206,8 @@ briefly describes the command or function's interface. For commands, this shows the syntax of the command and its arguments (including options); boldface is used for as-is text and italics are used to indicate replaceable -arguments. Brackets ([]) surround optional arguments, vertical bars (|) +arguments. +Brackets ([]) surround optional arguments, vertical bars (|) separate choices, and ellipses (\&...) can be repeated. For functions, it shows any required data declarations or .B #include @@ -261,7 +267,8 @@ and how they affect it. .TP .B DIAGNOSTICS gives an overview of the most common error messages and how to -cope with them. You don't need to explain system error messages +cope with them. +You don't need to explain system error messages or fatal signals that can appear during execution of any program unless they're special in some way to your program. .TP @@ -323,7 +330,8 @@ usually uses the macro). .IP Any reference to another man page (or to the subject of the current man -page) is in bold. If the manual section number is given, it is given in +page) is in bold. +If the manual section number is given, it is given in Roman (normal) font, without any spaces (e.g., .BR man (7)). .LP @@ -365,9 +373,9 @@ Small (useful for acronyms) Traditionally, each command can have up to six arguments, but the GNU implementation removes this limitation (you might still want to limit yourself to 6 arguments for portability's sake). -Arguments are delimited by -spaces. Double quotes can be used to specify an argument which contains -spaces. All of the arguments will be printed next to each other without +Arguments are delimited by spaces. +Double quotes can be used to specify an argument which contains spaces. +All of the arguments will be printed next to each other without intervening spaces, so that the .B \&.BR command can be used to specify a word in bold followed by a mark of @@ -390,7 +398,7 @@ As a result, successive indented paragraphs can use the same indent without re-specifying the indent value. A normal (non-indented) paragraph resets the prevailing indent value to its default value (0.5 inches). -By default a given indent is measured in ens; +By default a given indent is measured in ens; try to use ens or ems as units for indents, since these will automatically adjust to font size changes. The other key macro definitions are: @@ -453,7 +461,8 @@ a period as the tag; this simplifies translation to other formats. .TP .BI \&.TP " i" -Begin paragraph with hanging tag. The tag is given on the next line, but +Begin paragraph with hanging tag. +The tag is given on the next line, but its results are like those of the .B \&.IP command. @@ -529,7 +538,8 @@ is being used, the macro package's definition of the URL macro will supersede the locally defined one. .PP -A number of other link macros are available. See +A number of other link macros are available. +See .BR groff_www (7) for more details. .SS "Miscellaneous Macros" @@ -575,7 +585,7 @@ Avoid using the various troff preprocessors .BR tbl (1), but try to use the .B IP -and +and .B TP commands instead for two-column tables). Avoid using computations; most other tools can't process them. @@ -653,7 +663,7 @@ macros instead). The condition test .RB ( if,ie ) should only have 't' or 'n' as the condition. -Only translations +Only translations .RB ( tr ) that can be ignored should be used. Font changes @@ -682,10 +692,12 @@ If you include URLs, use the full URL can automatically find the URLs. .PP Tools processing these files should open the file and examine the first -non-whitespace character. A period (.) or single quote (') +non-whitespace character. +A period (.) or single quote (') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an SGML/XML-based -file (such as HTML or Docbook). Anything else suggests simple ASCII +file (such as HTML or Docbook). +Anything else suggests simple ASCII text (e.g., a "catman" result). .PP Many man pages begin with '\e" followed by a space and a list of characters, |
