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/
