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

[Corinna Vinschen <vinschen at redhat dot com>]

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?

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

> * 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".

> * 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?


Thanks,
Corinna

-- 
Corinna Vinschen
Cygwin Maintainer
Red Hat

Attachment: pgpOwhUw5c9ry.pgp
Description: PGP signature