Various updates

diff --git a/man7/man.7 b/man7/man.7
index 085b1414f5465b51a24c060e5871da99f7015884..8a0ccc1d9df50854b2fce7344e6cfad4be79065c 100644 (file)
--- a/man7/man.7
+++ b/man7/man.7
@@ -30,7 +30,7 @@
 .\" Modified Sun Jan  6 18:26:25 2002 by Martin Schulze <joey@infodrom.org>
 .\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org>
 .\"
-.TH MAN 7 2004-07-27 "Linux" "Linux Programmer's Manual"
+.TH MAN 7 2007-05-17 "Linux" "Linux Programmer's Manual"
 .SH NAME
 man \- macros to format man pages
 .SH SYNOPSIS
@@ -70,8 +70,9 @@ Using the
 .B \-mandoc
 option is, however, recommended, since this will automatically detect which
 macro package is in use.
-.SH PREAMBLE
-The first command in a man page (after comment lines) should be
+.SS Preamble
+The first command in a man page (after comment lines, 
+that is, lines that start with \fB.\\"\fP) should be
 .RS
 .sp
 .B \&.TH
@@ -86,13 +87,14 @@ The title of the man page (e.g.,
 .IR MAN ).
 .TP
 .I section
-The section number the man page should be placed in (e.g.,
+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.
@@ -105,10 +107,11 @@ looking at:
 .IR "Linux 0.99.11" .
 .sp
 For library calls, use the source of the function:
-.IR GNU ", " "4.3BSD" ", " "Linux DLL 4.4.1" .
+.IR "GNU C Library" ", " GNU ", " "4.3BSD" ", " "Linux DLL 4.4.1" .
 .TP
 .I manual
-The title of the manual (e.g.,
+The title of the manual (e.g., for Section 2 and 3 pages in 
+the \fIman-pages\fI package, use
 .IR "Linux Programmer's Manual" ).
 .RE
 .PP
@@ -161,16 +164,16 @@ many of which only root can execute.
 .\" There are better sources of
 .\" information for kernel developers.
 .RE
-.SH SECTIONS
+.SS Sections
 Sections are started with
 .B \&.SH
 followed by the heading name.
-.\" The follwoing doesn't seem to be required (see Debian bug 411303),
+.\" The following doesn't seem to be required (see Debian bug 411303),
 .\" If the name contains spaces and appears
 .\" on the same line as
 .\" .BR \&.SH ,
 .\" then place the heading in double quotes.
-The list below shows conventional or suggested sewctions.
+The list below shows conventional or suggested sections.
 Most manual pages should include at least the 
 .B highlighted
 sections.
@@ -207,9 +210,13 @@ EXAMPLE
 .in
 .IR "Where a traditional heading would apply, please use it" ;
 this kind of consistency can make the information easier to understand.
-If you really feel it necessary, you cann create your own 
+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:
 .RS
@@ -330,7 +337,7 @@ describes any standards or conventions this implements.
 .TP
 .B NOTES
 provides miscellaneous notes.
-.\" FIXME -- mention .SS Linux Notes and .SS Glib Notes?
+.\" FIXME -- mention .SS Linux Notes and .SS Glibc Notes?
 .TP
 .B BUGS
 lists limitations, known defects or inconveniences,
@@ -342,7 +349,7 @@ 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 list
+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.
@@ -351,7 +358,7 @@ add a copyright notice as a comment in the source file.
 lists related man pages in alphabetical order, possibly followed by
 other related pages or documents.
 Conventionally this is the last section.
-.SH FONTS
+.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:
@@ -454,7 +461,7 @@ command can be used to specify a word in bold followed by a mark of
 punctuation in Roman.
 If no arguments are given, the command is applied to the following line
 of text.
-.SH "OTHER MACROS AND STRINGS"
+.SS "Other Macros and Strings"
 .PP
 Below are other relevant macros and predefined strings.
 Unless noted otherwise, all macros
@@ -645,7 +652,7 @@ Trademark Symbol: \*(Tm
 Left angled doublequote: \*(lq
 .IP \e*(rq
 Right angled doublequote: \*(rq
-.SH "SAFE SUBSET"
+.SS "Safe Subset"
 Although technically
 .B man
 is a troff macro package, in reality a large number of other tools