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

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


  reply index

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-20  6:30 Michael Kerrisk (man-pages)
2020-05-20 11:05 ` Karel Zak [this message]
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=20200520110540.iw42lp3fdawed6gq@ws.net.home \
    --to=kzak@redhat.com \
    --cc=mtk.manpages@gmail.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