Util-Linux Archive on lore.kernel.org
 help / color / Atom feed
From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Karel Zak <kzak@redhat.com>
Cc: util-linux@vger.kernel.org
Subject: Section ordering in util-linux manual pages
Date: Wed, 20 May 2020 08:30:55 +0200
Message-ID: <CAKgNAkjU+HdQ2PQLtrPbVU2cyUYecOZZV3i6CSeDvWJM_OR3qQ@mail.gmail.com> (raw)

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/

             reply index

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-20  6:30 Michael Kerrisk (man-pages) [this message]
2020-05-20 11:05 ` Karel Zak
2020-05-21  7:28   ` Michael Kerrisk (man-pages)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CAKgNAkjU+HdQ2PQLtrPbVU2cyUYecOZZV3i6CSeDvWJM_OR3qQ@mail.gmail.com \
    --to=mtk.manpages@gmail.com \
    --cc=kzak@redhat.com \
    --cc=util-linux@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Util-Linux Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/util-linux/0 util-linux/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 util-linux util-linux/ https://lore.kernel.org/util-linux \
		util-linux@vger.kernel.org
	public-inbox-index util-linux

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.util-linux


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git