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

[Jeff Johnston <jjohnstn at redhat dot com>]

----- Original Message -----
> On Jul 21 13:37, Jon TURNEY wrote:
> > 
> > As I wrote a while ago, I've been looking for a better way to generate the
> > Cygwin package containing manpages for newlib.
> > 
> > Attached is a patch implementing a replacement for the makedoc tool, which
> > generates DocBook XML rather than .texinfo, which can then be processed
> > into
> > manpages and other formats.
> > 
> > I would appreciate any comments you have on the approach and the
> > implementation.
> > 
> > 
> > There are at least the following issues with this patch:
> > 
> > * 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?
> 

If that is the case, what are we buying with a rewrite?  How much better
are the man pages going to be?  What specifically are the functions at issue and
why can't they be fixed/improved by modifying the existing data?

> > * There's a lot of boilerplate in all the Makefiles to generate
> > documentation, and this adds more.  I don't know why this isn't in
> > Makefile.shared
> 
> Historical oversight, I guess.  Feel free to move as much of the shared
> stuff into Makefile.shared.

Agree.

> 
> > * 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.
> 
> Ok, so that's probably what we should do.  That allows to generate
> almost any other format one can think of, PDF, PS, info, man, ...
> 
> The problem is probably just that "somebody has to do it".
> 

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.

> > * I haven't tested that documentation is correctly included/excluded
> > depending on the newlib configuration.
> > 
> > * build avoidance needs doing correctly
> > 
> > * 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.
> 
> Jeff, any input to this?
> 

The clause is in libc.texinfo and libm.texinfo and we should have the power to modify
it.

> 
> Thanks,
> Corinna
> 
> --
> Corinna Vinschen
> Cygwin Maintainer
> Red Hat
>