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@xxxxxxxxxx>
http://karelzak.blogspot.com
