Hello Karel,
Across the util-linux manual pages, and assuming you accept my patch
series from yesterday, the most common SH sections are:
129 .SH AVAILABILITY
129 .SH DESCRIPTION
129 .SH NAME
129 .SH SYNOPSIS
113 .SH SEE ALSO
106 .SH OPTIONS
87 .SH AUTHORS
34 .SH NOTES
33 .SH EXIT STATUS
30 .SH EXAMPLE
29 .SH ENVIRONMENT
24 .SH FILES
24 .SH HISTORY
18 .SH BUGS
9 .SH CONFORMING TO
7 .SH COMMANDS
6 .SH COLORS
6 .SH COPYRIGHT
4 .SH ARGUMENTS
4 .SH RETURN VALUE
However, there's quite a wild variability in the order of some of
these sections in individual pages, which can make it a little
difficult to find a section. I suggest that the order of sections
should be consistently something like:
NAME
SYNOPSIS
CONFIGURATION
DESCRIPTION
OPTIONS
EXIT STATUS
RETURN VALUE
ERRORS
ENVIRONMENT
FILES
VERSIONS
HISTORY
ATTRIBUTES
CONFORMING TO
NOTES
BUGS
EXAMPLE
AUTHORS
COPYRIGHT
SEE ALSO
AVAILABILITY
(Note that this list does not include all the sections listed above,
but I'll ignore those for the moment.)
Does that order sound reasonable to you. (It's an expanded version of
the suggested order in man-pages(7), with some additions to allow for
headings that are commonly used in util-linux manual pages.)
I'd like to send some patches to fix that ordering. I would not do
this all at once, but rather, one or section headers at a time,
probably starting with SEE ALSO/AVAILABILITY. Does this sound okay to
you?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
