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



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




[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]