aboutsummaryrefslogtreecommitdiffstats
path: root/man7/man.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/man.7')
-rw-r--r--man7/man.758
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,