Moved various text out of here into new man-pages.7.

author: Michael Kerrisk <mtk.manpages@gmail.com> 2007-05-22 23:42:37 +0000
committer: Michael Kerrisk <mtk.manpages@gmail.com> 2007-05-22 23:42:37 +0000
commit: e7cbacd4af51b6430ccb526c21df45bd147ac50f (patch)
tree: 7b782b4a0a261e0972197a829d563e1476b32e71 /man7/man.7
parent: 7d6707baf2162d1c53a5c39152ed6768591591e3 (diff)
download: man-pages-e7cbacd4af51b6430ccb526c21df45bd147ac50f.tar.gz
1 files changed, 16 insertions, 325 deletions
diff --git a/man7/man.7 b/man7/man.7
index bd3bd19f1d..fc3c4fb33f 100644
--- a/man7/man.7
+++ b/man7/man.7
@@ -52,7 +52,7 @@ This manual page explains the
 .B "groff tmac.an"
 macro package (often called the
 .B man
-macro package) and related conventions for creating manual (man) pages.
+macro package).
 This macro package should be used by developers when
 writing or porting man pages for Linux.
 It is fairly compatible with other
@@ -72,112 +72,28 @@ Using the
 .B \-mandoc
 option is, however, recommended, since this will automatically detect which
 macro package is in use.
-.SS Preamble
+.PP
+For conventions that should be employed when writing man pages
+for the Linux \fIman-pages\fP package, see
+.BR man-pages (7).
+.SS Title line
 The first command in a man page (after comment lines, 
 that is, lines that start with \fB.\\"\fP) should be
 .RS
 .sp
 .B \&.TH
-.IR "title section date source manual" ,
+.IR "title section date source manual"
 .sp
 .RE
-where:
-.RS
-.TP 10
-.I title
-The title of the man page, wrtten in all caps (e.g.,
-.IR MAN ).
-.TP
-.I section
-The section number in which the man page should be placed (e.g.,
-.IR 7 ).
-.TP
-.I date
-The date of the last revision\(emremember to change this every time a
-change is made to the man page, since this is the most general way of doing
-version control.
-Dates should be written in the form YYYY-MM-DD.
-.TP
-.I source
-The source of the command, function, or system call.
-.sp
-For those few pages in Sections 1 and 8, probably you just want to write
-.IR GNU .
-.sp
-For system calls, just write
-.IR "Linux" .
-(An earlier practice was to write the version number
-of the kernel from which the manual page was being written/checked.
-However, this was never done consistently, and so was
-probably worse than including no version number.
-Henceforth, avoid including a version number.)
-.sp
-For library calls that are part of glibc or one of the 
-other common GNU libraries, just use
-.IR "GNU C Library" ", " GNU ,
-or an empty string.
-.sp
-For section 4 pages, use
-.IR "Linux" .
-.sp
-In cases of doubt, just write
-.IR Linux ", or " GNU .
-.TP
-.I manual
-The title of the manual (e.g., for Section 2 and 3 pages in 
-the \fIman-pages\fP package, use
-.IR "Linux Programmer's Manual" ).
-.RE
+For details of the arguments that should be supplied to the \fBTH\fI
+command, see
+.BR man-pages (7).
 .PP
 Note that BSD mdoc-formatted pages begin with the
 .B Dd
 command, not the
 .B TH
 command.
-.PP
-The manual sections are traditionally defined as follows:
-.RS
-.TP 10
-.B 1 Commands (Programs)
-Those commands that can be executed by the user from within
-a shell.
-.TP
-.B 2 System calls
-Those functions which must be performed by the kernel.
-.TP
-.B 3 Library calls
-Most of the
-.I libc
-functions.
-.TP
-.B 4 Special files (devices)
-Files found in
-.IR /dev .
-.TP
-.B 5 File formats and conventions
-The format for
-.I /etc/passwd
-and other human-readable files.
-.TP
-.B 6 Games
-.TP
-.B 7 Conventions and miscellaneous
-Overviews of various topics, conventions and protocols,
-character set standards, and miscellaneous other things.
-.TP
-.B 8 System management commands
-Commands like
-.BR mount (8),
-many of which only root can execute.
-.\" .TP
-.\" .B 9 Kernel routines
-.\" 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.
-.RE
 .SS Sections
 Sections are started with
 .B \&.SH
@@ -187,50 +103,6 @@ followed by the heading name.
 .\" on the same line as
 .\" .BR \&.SH ,
 .\" then place the heading in double quotes.
-The list below shows conventional or suggested sections.
-Most manual pages should include at least the 
-.B highlighted
-sections.
-Please try to arrange a new manual page so that sections
-are placed in approximately the order shown in the list.
-.in +0.5i
-.nf
-
-\fBNAME\fP
-\fBSYNOPSIS\fP
-\fBDESCRIPTION\fP
-OPTIONS            [Normally only in sections 1, 8]
-ENVIRONMENT
-FILES
-VERSIONS           [Normally only in sections 2, 3]
-RETURN VALUE       [Normally only in sections 2, 3]
-EXIT STATUS        [Normally only in sections 1, 8]
-.\" May 07: Few current man pages have an ERROR HANDLING section,,,
-.\" ERROR HANDLING,
-ERRORS             [Typically only in sections 2, 3]
-.\" May 07: Almost no current man pages have a USAGE section,,,
-.\" USAGE, 
-..\" DIAGNOSTICS, 
-.\" May 07: Almost no current man pages have a SECURITY section,,,
-.\" SECURITY,
-CONFORMING TO
-NOTES
-BUGS
-.\" AUTHOR sections are discouraged
-.\" AUTHOR, 
-EXAMPLE
-\fBSEE ALSO\fP
-
-.fi
-.in
-.IR "Where a traditional heading would apply" ", " "please use it" ;
-this kind of consistency can make the information easier to understand.
-If you must, you can create your own 
-headings if they make things easier to understand (this can
-be especially useful for pages in sections 4 and 5).
-However, before doing this, consider whether you could use the
-traditional headings, with some subsections (\fI.SS\fP) within
-those sections.
 
 The only mandatory heading is NAME, which should be the first section and
 be followed on the next line by a one line description of the program:
@@ -238,7 +110,6 @@ be followed on the next line by a one line description of the program:
 .sp
 \&.SH NAME
 .br
-chess \\- the game of chess
 .sp
 .RE
 It is extremely important that this format is followed, and that there is a
@@ -251,190 +122,9 @@ and
 .BR apropos (1)
 commands.
 .PP
-Some other traditional sections have the following contents:
-.TP 14
-.B SYNOPSIS
-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 (|)
-separate choices, and ellipses (\&...) can be repeated.
-For functions, it shows any required data declarations or
-.B #include
-directives, followed by the function declaration.
-.TP
-.B DESCRIPTION
-gives an explanation of what the program, function, or format does.
-Discuss how it interacts with files and standard input, and what it
-produces on standard output or standard error.
-Omit internals and implementation details unless they're critical for
-understanding the interface.
-Describe the usual case;
-for information on command-line options of a program use the
-.B OPTIONS
-section.
-.\" If there is some kind of input grammar or complex set of subcommands,
-.\" consider describing them in a separate
-.\" .B USAGE
-.\" section (and just place an overview in the
-.\" .B DESCRIPTION
-.\" section).
-.TP
-.B RETURN VALUE
-gives a
-list of the values the library routine will return to the caller
-and the conditions that cause these values to be returned.
-.TP
-.B EXIT STATUS
-lists the possible exit status values of a program and
-the conditions that cause these values to be returned.
-This section should only appear for Section 1 and 8 manual pages.
-.TP
-.B OPTIONS
-describes the command-line options accepted by a 
-program and how they change its behavior.
-This section should only appear for Section 1 and 8 manual pages.
-.\" .TP
-.\" .B USAGE
-.\" describes the grammar of any sublanguage this implements.
-.\" FIXME document VERSIONS
-.\" FIXME document other common Section Heading types
-.\" FIXME make a clear statement about the order of Sections
-.TP
-.B EXAMPLE
-provides one or more examples describing how this function, file or
-command is used.
-.TP
-.B FILES
-lists the files the program or function uses, such as
-configuration files, startup files,
-and files the program directly operates on.
-Give the full pathname of these files, and use the installation
-process to modify the directory part to match user preferences.
-For many programs, the default installation location is in
-.IR /usr/local ,
-so your base manual page should use
-.I /usr/local
-as the base.
-.TP
-.B ENVIRONMENT
-lists all environment variables that affect the program or function
-and how they affect it.
-.\" May 07: Almost no current man pages have a DIAGNOSTICS section;
-.\"         "RETURN VALUE" or "EXIT STATUS" is preferred.
-.\" .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
-.\" or fatal signals that can appear during execution of any program
-.\" unless they're special in some way to the program.
-.\"
-.\" May 07: Almost no current man pages have a SECURITY section.
-.\".TP
-.\".B SECURITY
-.\"discusses security issues and implications.
-.\"Warn about configurations or environments that should be avoided,
-.\"commands that may have security implications, and so on, especially
-.\"if they aren't obvious.
-.\"Discussing security in a separate section isn't necessary;
-.\"if it's easier to understand, place security information in the
-.\"other sections (such as the
-.\" .B DESCRIPTION
-.\" or
-.\" .B USAGE
-.\" section).
-.\" However, please include security information somewhere!
-.TP
-.B VERSIONS
-A brif summary of the Linux kernel or glibc versions where a
-system call or library function appeared,
-or changed significantly in its operation.
-.TP
-.B CONFORMING TO
-describes any standards or conventions this implements.
-.TP
-.B NOTES
-provides miscellaneous notes.
-.\" FIXME -- mention .SS Linux Notes and .SS Glibc Notes?
-.TP
-.B BUGS
-lists limitations, known defects or inconveniences,
-and other questionable activities.
-.TP
-.B AUTHOR
-lists authors of the documentation or program so you can mail in bug
-reports.
-.IR "Use of an AUTHOR section is discouraged".
-(One exception is section 4 pages that list the authors of
-device drivers, to whom software bugs should be sent.)
-Generally, it is better not to clutter every page with a list
-of (over time potentially numerous) authors;
-if you write or significantly amend a page,
-add a copyright notice as a comment in the source file.
-.TP
-.B SEE ALSO
-lists related man pages in alphabetical order, possibly followed by
-other related pages or documents.
-Conventionally this is the last section.
+For a list of other sections that might appear in a manual page, see
+.BR man-pages (7).
 .SS Fonts
-Although there are many arbitrary conventions for man pages in the UNIX
-world, the existence of several hundred Linux-specific man pages defines our
-font standards:
-.IP
-For functions, the arguments are always specified using italics,
-.IR "even in the SYNOPSIS section" ,
-where the rest of the function is specified in bold:
-.PP
-.RS
-.BI "    int myfunction(int " argc ", char **" argv );
-.RE
-.IP
-Filenames are always in italics (e.g.,
-.IR "/usr/include/stdio.h" ),
-except in the SYNOPSIS section, where included files are in bold (e.g.,
-.BR "#include <stdio.h>" ).
-.IP
-Special macros, which are usually in upper case, are in bold (e.g.,
-.BR MAXINT ).
-.IP
-When enumerating a list of error codes, the codes are in bold (this list
-usually uses the
-.B \&.TP
-macro).
-.IP
-Any reference to the subject of the current manual page
-should be written with the name in bold,
-followed by a pair of parentheses in Roman (normal) font,
-e.g.,
-.BR man ().
-The preferred way to write this in the source file is:
-.nf
-
-    .BR man ()
-
-.fi
-(Using this format, rather than the use of "\\fB...\\fP()"
-makes it easier to write tools that parse man page source files.)
-.IP
-Any reference to another man page
-should be written with the name in bold,
-\fIalways\fP followed by the section number,
-formatted in Roman (normal) font, without any
-separating spaces (e.g.,
-.BR intro (2)).
-The preferred way to write this in the source file is:
-.nf
-
-    .BR intro (2)
-
-.fi
-(Including the section number in cross references lets tools like
-.B man2html
-create properly hyperlinked pages.)
-.LP
 The commands to select the type face are:
 .TP 4
 .B \&.B
@@ -865,8 +555,9 @@ is not implemented.
 .BR groff (1),
 .BR man (1),
 .BR man2html (1),
-.BR mdoc (7),
-.BR mdoc.samples (7),
+.BR whatis (1),
 .BR groff_man (7),
 .BR groff_www (7),
-.BR whatis (1)
+.BR man-pages (7),
+.BR mdoc (7),
+.BR mdoc.samples (7)
author	Michael Kerrisk <mtk.manpages@gmail.com>	2007-05-22 23:42:37 +0000
committer	Michael Kerrisk <mtk.manpages@gmail.com>	2007-05-22 23:42:37 +0000
commit	e7cbacd4af51b6430ccb526c21df45bd147ac50f (patch)
tree	7b782b4a0a261e0972197a829d563e1476b32e71 /man7/man.7
parent	7d6707baf2162d1c53a5c39152ed6768591591e3 (diff)
download	man-pages-e7cbacd4af51b6430ccb526c21df45bd147ac50f.tar.gz