[RFC][PATCH] Make manpages via DocBook XML

[Jeff Johnston]

----- Original Message -----
> 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.
> 

The clause is in a Red Hat license which means it would be reasonable to assume
that Corinna or myself, representing Red Hat, would have the ability to modify it but IANAL.