Re: [xml] Update for libxslt/libxml manpages?

[Daniel Leidert <daniel leidert spam gmx net>]

Am Donnerstag, den 06.04.2006, 04:33 -0400 schrieb Daniel Veillard:
> On Thu, Apr 06, 2006 at 01:28:00AM +0200, Daniel Leidert wrote:

[..]
> > I would offer to rewrite these manpages in XML and fix the mentioned
> > bugs. As far as I understand Daniel's answer:
> >
> > > [..]
> > > > PS: Would you be interested in updated libxml(3) and libxslt(3) manpages
> > > > too? I could rewrite them in XML and fix a few bugs. One is, that these
> > >
> > >  That would be great. Actually one of the things I never took the
> > > time to do is to make XSLT stylesheets to generate man pages for the 
> > > functions entry points from doc/libxml2-api.xml and doc/libxslt-api.xml
> > > that's probably the simplest.
> > > [..]
> >
> > he suggests to use the libxml2-api.xml/libxslt-api.xml files and create
> > the manpages using these files, which seems to be a good idea to me. One
> > possible implementation: The manpages get a basic structure
> > (refentry/refentryinfo + stuff currently mentioned in the existing
> > manpages) and inbound another XML document, which is created via XSLT
> > from the mentioned api-files. The resulting (refentry) XML file can then
> > be processed via xsltproc and the manpage is created. Your opinion?
>
>   The only danger is that there is more than a thousand entry point in
> libxml2 (closer to 2000 I guess), and
>   - we don't want one man page per entry that's unshippable

ACK.

>   - one page with all entry point is also a bit nightmarish
> maybe a split of one page per module would be more sensible.

ACK.

> This would also
> allow to avoid the generation of the man pages for stuff in 'internal' headers.
> Similary in libxslt we probably don't want to expose everything in the man
> pages. We can't remove exposed entry point from the API for ABI compatibility
> but hiding the doc for them sounds a good approach :-)

Ok. So I suggest

libxml2(3) : main manpage, describing the files and which modules exist
-> referencing each module (the latter is done by parsing the
libxml-api.xml file via XSLT)

libxml2-$module(3) : description and synopsis(?) of each module, created
from the related api.xml file via XSLT

Ditto for libxslt(3).

This scheme seems to be used (by default) for Perl documentation, but
also for some C/C++ libraries. Your opinion?

Regards, Daniel