Section ordering in util-linux manual pages

Section ordering in util-linux manual pages

[Michael Kerrisk (man-pages)]

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/

Re: Section ordering in util-linux manual pages

[Karel Zak]

On Wed, May 20, 2020 at 08:30:55AM +0200, Michael Kerrisk (man-pages) wrote:
> 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.)

Looks good. 

util-linux is collection from random authors and we (mostly) invested
our effort to code consolidation and unification in last years. So,
I'm happy to see that you want to do the same with man 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?

Go ahead.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: Section ordering in util-linux manual pages

[Michael Kerrisk (man-pages)]

On 5/20/20 1:05 PM, Karel Zak wrote:
> On Wed, May 20, 2020 at 08:30:55AM +0200, Michael Kerrisk (man-pages) wrote:
>> 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

In the end, VERSIONS and ATTRIBUTES turned out to be irrelevant
(I have those sections in man-pages), and I moved HISTORY down
below notes, to produce the following order:

NAME
SYNOPSIS
CONFIGURATION
DESCRIPTION
OPTIONS
EXIT STATUS
RETURN VALUE
ERRORS
ENVIRONMENT
FILES
CONFORMING TO
NOTES
HISTORY
BUGS
EXAMPLE
AUTHORS
COPYRIGHT
SEE ALSO
AVAILABILITY

The above matches man-pages(7), but with some additions
(HISTORY, AVAILABILITY). The difference here is small enough
that maybe you could just add a note somewhere in the project
deferring to man-pages(7) for guidance?

Across the 120+ pages there remain somewhat more than 80
oddball section names. Perhaps some of that can be tidied up
with manual edits (e.g., using .SS instead of .SH). I may take
a look at a few of those pages.

>> (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.)
> 
> Looks good. 
> 
> util-linux is collection from random authors and we (mostly) invested
> our effort to code consolidation and unification in last years. So,
> I'm happy to see that you want to do the same with man 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?
> 
> Go ahead.

I [mis]said "one or [two] sections at a time". I've done the fixes 
rather around three section headers at a time, and in the end it was
three (large) patches, coming your way.

Finally, earlier, to address an inconsistency in the use of
EXAMPLE vs EXAMPLES in different pages, I switched everything 
to EXAMPLE (which is what I currently use in man-pages).
However, I did some investigation of a large corpus of manual
pages, and I see that EXAMPLES is rather more common than EXAMPLE,
and I also happened to see that EXAMPLES is what is in the POSIX
manual pages. So, I'm considering to switch that change in the
opposite direction util-linux, and I will also make the change in
man-pages.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/