24 files changed, 79 insertions, 76 deletions
diff --git a/man3/catopen.3 b/man3/catopen.3
index adef756d7e..ae346def46 100644
--- a/man3/catopen.3
+++ b/man3/catopen.3
@@ -140,7 +140,7 @@ The glibc value for NL_CAT_LOCALE is 1.
 (Compare MCLoadAll below.)
 The default path varies, but usually looks at a number of places below
 .IR /usr/share/locale .
-.SH "NOTES FOR LIBC4 AND LIBC5"
+.SH LINUX NOTES
 These functions are available for Linux since libc 4.4.4c.
 In the case of linux libc4 and libc5, the catalog descriptor
 .I nl_catd
diff --git a/man3/crypt.3 b/man3/crypt.3
index 92b97d1a18..7aca00bc1a 100644
--- a/man3/crypt.3
+++ b/man3/crypt.3
@@ -135,7 +135,7 @@ function was not implemented, probably because of U.S.A. export restrictions.
 .\" .PP
 .\" Making encrypted data computed using crypt() publicly available has
 .\" to be considered insecure for the given reasons.
-.SH "GNU EXTENSION"
+.SH GLIBC NOTES
 The glibc2 version of this function has the following additional features.
 If
 .I salt
diff --git a/man3/dbopen.3 b/man3/dbopen.3
index 139d467288..577d165511 100644
--- a/man3/dbopen.3
+++ b/man3/dbopen.3
@@ -367,7 +367,7 @@ manual page for more information.)
 routines return \-1 on error (setting
 .IR errno )
 and 0 on success.
-.SH "KEY/DATA PAIRS"
+.SS "Key/Data Pairs"
 Access to all file types is based on key/data pairs.
 Both keys and data are represented by the following data structure:
 .PP
diff --git a/man3/des_crypt.3 b/man3/des_crypt.3
index 61a3e063cd..3df7048faf 100644
--- a/man3/des_crypt.3
+++ b/man3/des_crypt.3
@@ -107,7 +107,7 @@ vector upon return.
 .\" added, aeb
 and
 .BR xcrypt (3)
-.SH DIAGNOSTICS
+.SH RETURN VALUE
 .PD 0
 .TP 20
 .SM DESERR_NONE
diff --git a/man3/dlopen.3 b/man3/dlopen.3
index 3bedbf514f..c0dab3e43e 100644
--- a/man3/dlopen.3
+++ b/man3/dlopen.3
@@ -321,7 +321,7 @@ Constructor routines are executed before
 returns, and destructor routines are executed before
 .BR dlclose ()
 returns.
-.SH "GNU EXTENSIONS"
+.SH GLIB NOTES
 Glibc adds two functions not described by POSIX, with prototypes
 .sp
 .nf
@@ -428,7 +428,7 @@ Since glibc 2.2.3,
 .BR atexit (3)
 can be used to register an exit handler that is automatically
 called when a library is unloaded.
-.SH HISTORY
+.SS History
 The dlopen interface standard comes from SunOS.
 That system also has
 .BR dladdr (),
diff --git a/man3/exec.3 b/man3/exec.3
index a02b63eb60..933d798eb1 100644
--- a/man3/exec.3
+++ b/man3/exec.3
@@ -175,7 +175,7 @@ for any of the errors specified for the library function
 .BR ptrace (2),
 .BR fexecve (3),
 .BR environ (7)
-.SH COMPATIBILITY
+.SH NOTES
 On some other systems the default path (used when the environment
 does not contain the variable \fBPATH\fR) has the current working
 directory listed after
diff --git a/man3/fenv.3 b/man3/fenv.3
index d6a9b6fdb0..454222cade 100644
--- a/man3/fenv.3
+++ b/man3/fenv.3
@@ -207,7 +207,7 @@ These functions return zero on success and non-zero if an error occurred.
 .\" Earlier seven of these functions were listed as returning void.
 .\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E))
 .\" of the C99 Standard.
-.SH "GNU DETAILS"
+.SH GLIBC NOTES
 If possible, the GNU C Library defines a macro
 .B FE_NOMASK_ENV
 which represents an environment where every exception raised causes a
diff --git a/man3/fopen.3 b/man3/fopen.3
index 7a7fae1ab7..4f4c72f17a 100644
--- a/man3/fopen.3
+++ b/man3/fopen.3
@@ -236,7 +236,7 @@ functions conform to C89.
 The
 .BR fdopen ()
 function conforms to POSIX.1-1990.
-.SH "GLIBC EXTENSIONS"
+.SH "GLIBC NOTES"
 The GNU C library allows the following extensions for the string specified in
 .IR mode :
 .TP
diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3
index cbff63fbe0..911f3d8105 100644
--- a/man3/gethostbyname.3
+++ b/man3/gethostbyname.3
@@ -250,7 +250,48 @@ host database file
 name service switch configuration
 .SH "CONFORMING TO"
 4.3BSD, POSIX.1-2001.
-.SH "SYSTEM V/POSIX EXTENSION"
+.SH NOTES
+The functions
+.BR gethostbyname ()
+and
+.BR gethostbyaddr ()
+may return pointers to static data, which may be overwritten by
+later calls.
+Copying the
+.I struct hostent
+does not suffice, since it contains pointers; a deep copy is required.
+.LP
+The SUS-v2 standard is buggy and declares the
+.I len
+parameter of
+.BR gethostbyaddr ()
+to be of type
+.IR size_t .
+(That is wrong, because it has to be
+.IR int ,
+and
+.I size_t
+is not.
+POSIX.1-2001 makes it
+.IR socklen_t ,
+which is OK.)
+.LP
+The BSD prototype for
+.BR gethostbyaddr ()
+uses
+.I const char *
+for the first argument.
+.LP
+POSIX.1-2001 marks
+.BR gethostbyaddr ()
+and
+.BR gethostbyname ()
+obsolescent.
+See
+.BR getaddrinfo (3),
+.BR getnameinfo (3),
+.BR gai_strerror (3).
+.SS "System V/POSIX Extension"
 POSIX requires the
 .BR gethostent ()
 call, that should return the next entry in the host data base.
@@ -267,7 +308,7 @@ The glibc version will ignore ipv6 entries.
 This function is not reentrant,
 and glibc adds a reentrant version
 .BR gethostent_r ().
-.SH "GNU EXTENSIONS"
+.SS "GNU Extensions"
 Glibc2 also has a
 .BR gethostbyname2 ()
 that works like
@@ -296,47 +337,6 @@ No global variable
 is modified, but the address of a variable in which to store error numbers
 is passed in
 .IR h_errnop .
-.SH NOTES
-The functions
-.BR gethostbyname ()
-and
-.BR gethostbyaddr ()
-may return pointers to static data, which may be overwritten by
-later calls.
-Copying the
-.I struct hostent
-does not suffice, since it contains pointers; a deep copy is required.
-.LP
-The SUS-v2 standard is buggy and declares the
-.I len
-parameter of
-.BR gethostbyaddr ()
-to be of type
-.IR size_t .
-(That is wrong, because it has to be
-.IR int ,
-and
-.I size_t
-is not.
-POSIX.1-2001 makes it
-.IR socklen_t ,
-which is OK.)
-.LP
-The BSD prototype for
-.BR gethostbyaddr ()
-uses
-.I const char *
-for the first argument.
-.LP
-POSIX.1-2001 marks
-.BR gethostbyaddr ()
-and
-.BR gethostbyname ()
-obsolescent.
-See
-.BR getaddrinfo (3),
-.BR getnameinfo (3),
-.BR gai_strerror (3).
 .SH "SEE ALSO"
 .BR getaddrinfo (3),
 .BR getipnodebyaddr (3),
diff --git a/man3/getrpcent.3 b/man3/getrpcent.3
index b4022c9690..afd7c480bf 100644
--- a/man3/getrpcent.3
+++ b/man3/getrpcent.3
@@ -100,7 +100,7 @@ Present on the BSDs, Solaris, and many other systems.
 .BR rpc (5),
 .BR rpcinfo (8),
 .BR ypserv (8)
-.SH DIAGNOSTICS
+.SH RETURN VALUE
 .LP
 A
 .SM NULL
diff --git a/man3/getsubopt.3 b/man3/getsubopt.3
index ec28334dd6..f9353ed284 100644
--- a/man3/getsubopt.3
+++ b/man3/getsubopt.3
@@ -121,7 +121,7 @@ Since
 overwrites any commas it finds in the string
 .RI * optionp ,
 that string must be writable; it cannot be a string constant.
-.SH EXAMPLE PROGRAM
+.SH EXAMPLE
 The following program excepts suboptions following a "-o" option.
 
 .nf
diff --git a/man3/getutent.3 b/man3/getutent.3
index fa9d52c9f8..bd979fbd20 100644
--- a/man3/getutent.3
+++ b/man3/getutent.3
@@ -110,7 +110,7 @@ and
 return a pointer to a \fBstruct utmp\fP on success, and NULL on failure.
 This \fBstruct utmp\fP is allocated in static storage, and may be
 overwritten by subsequent calls.
-.SH "REENTRANT VERSIONS"
+.SH GLIBC NOTES
 The above functions are not thread-safe.
 Glibc adds reentrant versions
 .sp
diff --git a/man3/insque.3 b/man3/insque.3
index bebfebfa99..221c5a5e9e 100644
--- a/man3/insque.3
+++ b/man3/insque.3
@@ -57,7 +57,7 @@ removes the element pointed to by \fIelem\fP from the
 doubly-linked list.
 .SH "CONFORMING TO"
 POSIX.1-2001
-.SH "HISTORICAL NOTES"
+.SH "NOTES"
 Traditionally (e.g. SunOS, Linux libc 4,5) the parameters of these
 functions were of type \fIstruct qelem *\fP, where the struct
 is defined as
diff --git a/man3/login.3 b/man3/login.3
index c216314816..94262d5289 100644
--- a/man3/login.3
+++ b/man3/login.3
@@ -45,7 +45,7 @@ and writes it to both utmp and wtmp file.
 The function
 .BR logout ()
 clears the entry in the utmp file again.
-.SH "GNU DETAILS"
+.SS "GNU Details"
 More precisely,
 .BR login ()
 takes the argument
diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3
index 0ea37049b8..5ab1377a7e 100644
--- a/man3/posix_memalign.3
+++ b/man3/posix_memalign.3
@@ -163,7 +163,7 @@ appears in SunOS 4.1.3 but not in 4.4BSD.
 The function
 .BR posix_memalign ()
 comes from POSIX.1d.
-.SH HEADERS
+.SS Headers
 Everybody agrees that
 .BR posix_memalign ()
 is declared in <stdlib.h>.
diff --git a/man3/regex.3 b/man3/regex.3
index 707541b76f..2506a23c4f 100644
--- a/man3/regex.3
+++ b/man3/regex.3
@@ -50,7 +50,8 @@ regcomp, regexec, regerror, regfree \- POSIX regex functions
 .BI "size_t " errbuf_size );
 .xx \w'\fBvoid\ regfree(\fR'
 .BI "void\ regfree(regex_t *" preg );
-.SH "POSIX REGEX COMPILING"
+.SH DESCRIPTION
+.SS "POSIX Regex Compiling"
 .BR regcomp ()
 is used to compile a regular expression into a form that is suitable
 for subsequent
@@ -127,7 +128,7 @@ whether
 .IR eflags
 contains
 .BR REG_NOTEOL .
-.SH "POSIX REGEX MATCHING"
+.SS "POSIX Regex Matching"
 .BR regexec ()
 is used to match a null-terminated string
 against the precompiled pattern buffer,
@@ -201,7 +202,7 @@ substring match within the string.
 The relative
 .I rm_eo
 element indicates the end offset of the match.
-.SH "POSIX ERROR REPORTING"
+.SS "Posix Error Reporting"
 .BR regerror ()
 is used to turn the error codes that can be returned by both
 .BR regcomp ()
@@ -230,7 +231,7 @@ are non-zero,
 is filled in with the first
 .I "errbuf_size \- 1"
 characters of the error message and a terminating null.
-.SH "POSIX PATTERN BUFFER FREEING"
+.SS "POSIX Pattern Buffer Freeing"
 Supplying
 .BR regfree ()
 with a precompiled pattern buffer,
diff --git a/man3/scanf.3 b/man3/scanf.3
index f6af7367e7..b8a236a64c 100644
--- a/man3/scanf.3
+++ b/man3/scanf.3
@@ -254,7 +254,7 @@ be placed in the location referred to by the
 .I pointer
 argument following
 .IR format .
-.SH CONVERSIONS
+.SS Conversions
 The following
 .IR "type modifier characters"
 can appear in a conversion specification:
diff --git a/man3/stdarg.3 b/man3/stdarg.3
index a62614848a..465aeb4302 100644
--- a/man3/stdarg.3
+++ b/man3/stdarg.3
@@ -208,6 +208,7 @@ takes a string of format characters and prints out the argument associated
 with each format character based on the type.
 .RS
 .nf
+
 #include <stdio.h>
 #include <stdarg.h>
 
@@ -250,16 +251,17 @@ macros conform to C89.
 C99 defines the
 .BR va_copy ()
 macro.
-.SH COMPATIBILITY
+.SH NOTES
 These macros are
 .I not
 compatible with the historic macros they replace.
 A backward compatible version can be found in the include file
 .IR varargs.h .
-.SH COMPARISON
+.PP
 The historic setup is:
-.RS
+.in +0.5i
 .nf
+
 #include <varargs.h>
 
 void
@@ -276,8 +278,9 @@ foo(va_alist)
     }
     va_end(ap);
 }
+
 .fi
-.RE
+.in
 On some systems,
 .I va_end
 contains a closing '}' matching a '{' in
diff --git a/man3/stdio.3 b/man3/stdio.3
index c7212acf2f..f2f9da3ec8 100644
--- a/man3/stdio.3
+++ b/man3/stdio.3
@@ -178,7 +178,7 @@ Function versions of the macro functions
 and
 .B putchar
 exist and will be used if the macros definitions are explicitly removed.
-.SH "LIST OF FUNCTIONS"
+.SS "List of Functions"
 .TP 10n
 .B Function
 .B Description
diff --git a/man3/strptime.3 b/man3/strptime.3
index 5f7e5cc243..3c2df130d8 100644
--- a/man3/strptime.3
+++ b/man3/strptime.3
@@ -295,7 +295,7 @@ main(void)
     exit(EXIT_SUCCESS);
 }
 .fi
-.SH "GNU EXTENSIONS"
+.SH GLIBC NOTES
 For reasons of symmetry, glibc tries to support for
 .BR strptime ()
 the same format characters as for
diff --git a/man3/sysconf.3 b/man3/sysconf.3
index 12fe6e8be4..4c25fbd56c 100644
--- a/man3/sysconf.3
+++ b/man3/sysconf.3
@@ -99,7 +99,7 @@ The
 .BR sysconf ()
 argument will be
 .BR _SC_FOO .
-.SH "POSIX.1 VARIABLES"
+.SS "POSIX.1 Variables"
 We give the name of the variable, the name of the
 .BR sysconf ()
 parameter used to inquire about its value,
@@ -197,7 +197,7 @@ format
 value
 .B 199009L
 indicates the Sept. 1990 revision.
-.SH "POSIX.2 VARIABLES"
+.SS "POSIX.2 Variables"
 Next, the POSIX.2 values, giving limits for utilities.
 .TP
 .BR BC_BASE_MAX " - " _SC_BC_BASE_MAX
diff --git a/man3/syslog.3 b/man3/syslog.3
index a2236bfe21..4631d20ac1 100644
--- a/man3/syslog.3
+++ b/man3/syslog.3
@@ -114,8 +114,8 @@ with the difference that it takes a set of arguments which have
 been obtained using the
 .BR stdarg (3)
 variable argument list macros.
-.SH PARAMETERS
-This section lists the parameters used to set the values of
+
+The subsections below lists the parameters used to set the values of
 .IR option , " facility" ", and " priority .
 .SS option
 The
diff --git a/man3/wordexp.3 b/man3/wordexp.3
index 110257e421..9de907f9c8 100644
--- a/man3/wordexp.3
+++ b/man3/wordexp.3
@@ -71,7 +71,7 @@ More precisely, it does not free
 its argument, but it frees the array
 .I we_wordv
 and the strings that points to.
-.SH EXAMPLE
+.SS Example
 First a small example.
 The output is approximately that of "ls [a-c]*.c".
 .LP
@@ -94,7 +94,6 @@ main(int argc, char **argv)
     exit(EXIT_SUCCESS);
 }
 .fi
-.SH DETAILS
 .SS "The string argument"
 Since the expansion is the same as the expansion by the shell (see
 .BR sh (1))
diff --git a/man4/console.4 b/man4/console.4
index c60dc9429e..b96071d939 100644
--- a/man4/console.4
+++ b/man4/console.4
@@ -60,7 +60,7 @@ The command
 (formerly \fBdisalloc\fP)
 will free the memory taken by the screen buffers for consoles
 that no longer have any associated process.
-.SH PROPERTIES
+.SS Properties
 Consoles carry a lot of state.
 I hope to document that some other time.
 The most important fact is that the consoles simulate vt100 terminals.