Consistency fixes in util-linux man pages

Consistency fixes in util-linux man pages

[Michael Kerrisk (man-pages)]

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?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: Consistency fixes in util-linux man pages

[Karel Zak]

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, 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.

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?

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: Consistency fixes in util-linux man pages

[Michael Kerrisk (man-pages)]

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/

Re: Consistency fixes in util-linux man pages

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 1711 bytes --]

Hello Michael and Karel,
On Mon, May 18, 2020 at 12:36:01PM +0200, Michael Kerrisk (man-pages) wrote:
> On Mon, 18 May 2020 at 10:28, Karel Zak <kzak@redhat.com> wrote:
> > 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.

Even though man pages are limitted in formatting, they are universally
available and, from our POV, getting more attention from the
translators side. We just welcomed our seventh language. Probably not 
relevant for kenel side docs, but for programs by non programmers (and 
presumably non native speakers) man pages are good option.

(Of course, translation tools for other formats exists and e.g. po4a
supports many formats, it also need a dedicated community of
translators).

Greetings

           Helge

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Consistency fixes in util-linux man pages

[Karel Zak]

On Mon, May 18, 2020 at 05:03:13PM +0200, Helge Kreutzmann wrote:
> On Mon, May 18, 2020 at 12:36:01PM +0200, Michael Kerrisk (man-pages) wrote:
> > I'm not too knowledgeable in AsciiDc, but my impression is that it's
> > too limited in terms of its formatting opinions.

Yes, I'm not sure about AsciiDoc limitations. For example systemd guys uses
DocBook which is probably ultimate solution.

> > 
> > 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.
> 
> Even though man pages are limitted in formatting, they are universally
> available and, from our POV, getting more attention from the
> translators side. We just welcomed our seventh language. Probably not 
> relevant for kenel side docs, but for programs by non programmers (and 
> presumably non native speakers) man pages are good option.

The idea is maintain documentation (in git tree) in some content
oriented language and then generate man pages from this content. It
means in the official release tarball will be man pages and end-users
will not see any difference.

The issue I have with man pages is that contributor very often send
patches to change formatting details and keep it consistent, avoid
color-of-bike-shed discussions is very difficult. It would be better
care about content and keep all the formatting details in some
conversion template.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: Consistency fixes in util-linux man pages

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 2546 bytes --]

Hello Karel,
On Tue, May 19, 2020 at 12:38:32PM +0200, Karel Zak wrote:
> On Mon, May 18, 2020 at 05:03:13PM +0200, Helge Kreutzmann wrote:
> > On Mon, May 18, 2020 at 12:36:01PM +0200, Michael Kerrisk (man-pages) wrote:
> > > I'm not too knowledgeable in AsciiDc, but my impression is that it's
> > > too limited in terms of its formatting opinions.
> 
> Yes, I'm not sure about AsciiDoc limitations. For example systemd guys uses
> DocBook which is probably ultimate solution.

I'm currently translating them. Also I've used DocBook myself to write
manges (a long time ago).

> > > 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.
> > 
> > Even though man pages are limitted in formatting, they are universally
> > available and, from our POV, getting more attention from the
> > translators side. We just welcomed our seventh language. Probably not 
> > relevant for kenel side docs, but for programs by non programmers (and 
> > presumably non native speakers) man pages are good option.
> 
> The idea is maintain documentation (in git tree) in some content
> oriented language and then generate man pages from this content. It
> means in the official release tarball will be man pages and end-users
> will not see any difference.

Ok, then this is fine.

> The issue I have with man pages is that contributor very often send
> patches to change formatting details and keep it consistent, avoid
> color-of-bike-shed discussions is very difficult. It would be better
> care about content and keep all the formatting details in some
> conversion template.

I strongly agree. Keep content and presentation separate. This also
helps us translators, even though we don't see the original markup, we
do quickly understand the results, because it is consistent, i.e. what
to translate and what to leave untranslated (e.g. command names vs.
variable names)

Greetings

            Helge
-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]