* Section ordering in util-linux manual pages @ 2020-05-20 6:30 Michael Kerrisk (man-pages) 2020-05-20 11:05 ` Karel Zak 0 siblings, 1 reply; 3+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-20 6:30 UTC (permalink / raw) To: Karel Zak; +Cc: util-linux 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/ ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Section ordering in util-linux manual pages 2020-05-20 6:30 Section ordering in util-linux manual pages Michael Kerrisk (man-pages) @ 2020-05-20 11:05 ` Karel Zak 2020-05-21 7:28 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 3+ messages in thread From: Karel Zak @ 2020-05-20 11:05 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: util-linux 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 ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Section ordering in util-linux manual pages 2020-05-20 11:05 ` Karel Zak @ 2020-05-21 7:28 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 3+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-21 7:28 UTC (permalink / raw) To: Karel Zak; +Cc: mtk.manpages, util-linux 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/ ^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-05-21 7:28 UTC | newest] Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-05-20 6:30 Section ordering in util-linux manual pages Michael Kerrisk (man-pages) 2020-05-20 11:05 ` Karel Zak 2020-05-21 7:28 ` Michael Kerrisk (man-pages)
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.