From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Karel Zak <kzak@redhat.com>
Cc: util-linux@vger.kernel.org, Helge Kreutzmann <debian@helgefjell.de>
Subject: Re: Consistency fixes in util-linux man pages
Date: Mon, 18 May 2020 12:36:01 +0200 [thread overview]
Message-ID: <CAKgNAkihsF1tGurfHbnFPYZ4qJV9-2f=Sbj5qdLxmuuuAJ+GGA@mail.gmail.com> (raw)
In-Reply-To: <20200518082814.pq22ph732eiebacz@ws.net.home>
Hello Karel,
On Mon, 18 May 2020 at 10:28, Karel Zak <kzak@redhat.com> wrote:
>
> On Sat, May 16, 2020 at 10:24:59AM +0200, Michael Kerrisk (man-pages) wrote:
> > Hello Karel,
> >
> > Perhaps a little inspired by Helge's recent reports, I wonder about
> > submitting some wide-ranging patches to improve consistency across
> > the util-linux manual pages.
> >
> > As an example, there's quite a bit of variation in the order of
> > .SH sections in the manual pages (e.g., in the placement of the SEE
> > ALSO section). The pages would be more readable if the ordering was
> > more consistent.
> >
> > Would you entertain patches that made wide-ranging changes
> > that fixed that sort of thing (without changing page content?
>
> No problem,
Ok.
> but it would be nice to somehow document that is expected
> to avoid future changes in an opposite way. For example add some info
> to Documentation/howto-man-page.txt.
Agreed. For man-pages, I created man-pags(7) to document those
expectations. At least some of that should be applicable in othe
pojects, if they want.
> BTW, I'm not sure about man pages as ideal format to maintain
> documentation (because it's mostly about formatting than about
> content). I think about AsciiDoc or so in future. What do you think
> about this idea?
I'm not too knowledgeable in AsciiDc, but my impression is that it's
too limited in terms of its formatting opinions.
If I did move man-pages, the most likely candidate would probably be
Sphinx, as is nowadays used in the kernel docs. But, that would
require converting a thousand pages or so, and I have not so far had
the stomach for that. Of course, you have a rather smaller set of
pages to deal with, so a conversion step sould be more easily
entertained.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
next prev parent reply other threads:[~2020-05-18 10:36 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-16 8:24 Consistency fixes in util-linux man pages Michael Kerrisk (man-pages)
2020-05-18 8:28 ` Karel Zak
2020-05-18 10:36 ` Michael Kerrisk (man-pages) [this message]
2020-05-18 15:03 ` Helge Kreutzmann
2020-05-19 10:38 ` Karel Zak
2020-05-19 17:23 ` Helge Kreutzmann
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='CAKgNAkihsF1tGurfHbnFPYZ4qJV9-2f=Sbj5qdLxmuuuAJ+GGA@mail.gmail.com' \
--to=mtk.manpages@gmail.com \
--cc=debian@helgefjell.de \
--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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).