[RFC][PATCH] Make manpages via DocBook XML

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

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.

* 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

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

[1] https://sourceforge.net/p/docbook/bugs/1362/

Attachment: 0001-Make-newlib-manpages-via-DocBook-XML.patch
Description: Text document