Re: [RFC][PATCH] Make manpages via DocBook XML

[Jon TURNEY <jon dot turney at dronecode dot org dot uk>]

On 21/07/2015 20:24, Jeff Johnston wrote:
> > On Jul 21 13:37, Jon TURNEY wrote:
> > > * This only converts to DocBook the minimum necessary to generate manpages.
> > >
> > > Converting the full content of libc.texinfo, libm.texinfo, sys.tex,
> > > reent.tex, iconv.tex, etc. is hard to do automatically, so would need to be
> > > done by hand.
> > >
> > > Since maintaining the documentation in two formats seems unlikely to be a
> > > good idea, this would mean fully converting to DocBook, removing all the
> > > current texinfo source and .info generation and generating the .info from
> > > DocBook instead.
> >
> > Do I understand you correctly?  Do you suggest to convert the
> > documentation in the C files to DocBook XML format?

No.

Firstly, you might consider this a non-issue, and be happy with the 
approach of adding a mechanism for generating manpages, while leaving 
generating .info documentation as currently, as this patch does.

Secondly, that's not what I'm suggesting.

My aim was to make the minimum amount of change, so I wrote makedocbook 
(which processes makedoc markup and a very limited subset of texinfo 
markup into DocBook XML) avoid having to alter the existing 
documentation in C files.

As stated in the "Documentation" section of HOWTO, the current situation 
is that documentation in C files uses makedoc markup, and can also use 
any texinfo commands directly.

Additionally there are some handwritten .texinfo files.

I guess I am noting that it would be possible to change that so that 
documentation in the C files can use makedoc markup, the very limited 
subset of texinfo markup which is currently used, (and perhaps) DocBook 
markup (it's not clear this is necessary or a good idea)

Additionally, the handwritten .texinfo files would be converted to 
DocBook XML.

If you have suggestions as to how to achieve my goal of making manpages 
while making even less changes, I would very much like to hear them.

> > > * This fails to fully achieve the objective of generating good manpages.
> > > A
> > > few functions (e.g. sccanf, ssprintf) use nested tables in a way which
> > > can't
> > > be represented by troff markup (see [1]).  So the markup of the
> > > documentation for these functions would need to be improved, presumably by
> > > writing it directly in DocBook.

I should probably have written 'simplified or improved...', and also 
discussed the possibility of simplifying the markup used in the 
documentation for those functions to something which allows good 
manpages to be generated.

On reflection, and after looking at the linux man-pages for sscanf, 
ssprintf (which do not use tables at all), that seems the better approach.

> Again, not sure why this means everything has to be rewritten and not just
> a few functions modified.  Glibc uses texinfo documentation for stdio functions
> and presumably the man pages are generated from them so we should be able to
> do something similar.

This is a good question, but I don't think the presumption is correct.

By design, texinfo does not lend itself well to generating manpages.
(see 
http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Adding-Output-Formats)

The texinfo documentation for glibc is organized in a different manner 
to man pages (e.g for sscanf, see 
http://www.gnu.org/software/libc/manual/html_node/Formatted-Input-Functions.html 
and the surrounding sections)

There are also manpages, but those come from the linux man-pages 
project, and seem to be handwritten troff. (e.g. compare 
http://git.kernel.org/cgit/docs/man-pages/man-pages.git/tree/man3/scanf.3)

> > > * The documentation license contains a clause specifically permitting
> > > printing after processing with Tex. Presumably the copyright holder, Red
> > > Hat, would need to approve a change permitting printing after processing
> > > with other tools.
> >
> > The copyright holder is not Red Hat.  Many files have different
> > copyrights and copyright holders.  But I don't think that's a problem.
> > I assume that the general idea was to make sure that it's allowed to
> > print the docs in the first place.

Ok, I didn't know that newlib didn't require a copyright assignment.

> > Jeff, any input to this?
> The clause is in libc.texinfo and libm.texinfo and we should have the power to modify
> it.

I'm not sure in what sense 'should' is used here.