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

[Daniel Veillard <veillard redhat com>]

On Thu, Apr 06, 2006 at 01:28:00AM +0200, Daniel Leidert wrote:
> (x-post to xml and xslt list)
>
> Hello,
>
> I asked Daniel Veillard for an update of the libxml(2).3 and libxslt.3
> manpages distributed with the source. The current manpages are (maybe) a
> bit outdated and they contain one issue: 
>
> - they should not reference the full path in the files section
>
> Further libxml.3 should IMHO be renamed to libxml2.3. Your opinion?

  that is true, renaming would make sense.

> 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
  - one page with all entry point is also a bit nightmarish
maybe a split of one page per module would be more sensible. 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 :-)

  Thanks for looking at this,

Daniel

-- 
Daniel Veillard      | Red Hat http://redhat.com/
veillard redhat com  | libxml GNOME XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/