Re: [RFC][PATCH] Make manpages (v2)

[Corinna Vinschen <vinschen at redhat dot com>]

On Apr 12 12:32, Jon Turney wrote:
> 
> This is an update of my previous patch at [1]
> 
> Currently, newlib has no manpages.  Attached is a patch which generates
> manpages for newlib functions which have makedoc markup.
> 
> texinfo (by design) does not lend itself well to generating manpages, so
> instead DocBook XML is used as an intermediate format.
> 
> This patch adds a makedocbook tool, which, similarly to the makedoc tool,
> processes source files to extract markup, but rather than .texinfo, it
> generates DocBook XML, which can then be processed into manpages.
> 
> Similarly to the info documentation, the man pages are not built by 'make
> all', but by 'make doc', and can be installed with 'make install-man'.
> 
> This just adds a mechanism for generating manpages.  The current mechanisms
> for generating documentation in .info and other formats are unchanged and
> there is no suggestion to change that.
> 
> For ease of reviewing, this patch doesn't contain Makefile.in changes.
> 
> I would appreciate any comments you have on the approach and the
> implementation.
> 
> There are at least the following issues with this patch:
> 
> * I haven't tested that documentation is correctly included/excluded
> depending on the newlib configuration.
> 
> * Like 'make info', there is only build avoidance for extracting markup from
> the source, not for the processing of that extracted markup.

The approach looks good to me.  The additionally dependency to python
for generating the man pages makes me a bit uncomfortable, though.
Since `make doc' didn't require python so far, maybe the creation of
man pages should be separated from that?


Corinna

-- 
Corinna Vinschen
Cygwin Maintainer
Red Hat

Attachment: signature.asc
Description: PGP signature