Re: API documentation from introspection data

[Shaun McCance <shaunm gnome org>]

On Tue, 2012-02-21 at 17:08 +0100, Stefan Sauer wrote:
> On 02/19/2012 03:41 PM, Shaun McCance wrote:
> > On Sun, 2012-02-19 at 12:48 +0100, Stefan Sauer wrote:
> >> Just one thought. If people work on a next generation doc tool to take
> >> over from gtk-doc, please consider to do it without docbook xml at
> >> all.
> >> Just go from an intermediate representation to html *without* xslt.
> >> libxslt is literally dead and other processors are even slower.
> > libxslt is not slow. The XSLT stylesheets that gtk-doc uses are slow.
> > It's true that it's not really actively developed, but it's basically
> > complete as an XSLT 1.0 processor and doesn't need to be constantly
> > changed.
> Yes, you are partially right. But its both. For once libxslt is single
> threaded (also on chunked output).

Sort of. It's safe to run multiple xsltTransformContexts concurrently
in libxslt, but it's not a good idea to have multiple threads handle
a single xsltTransformContext. (Off the top of my head, I'm almost
certain the way xslt:key is implemented on-demand isn't thread-safe.)

But Yelp runs multiple transforms concurrently for Mallard pages. It
doesn't run a single transform to do all pages. It transforms each
page on-demand, and each with a separate transform. This works fine.
If yelp-build were a C program instead of a shell script, it could
do the same thing to create HTML files.

> Just saying, that it might be a good occation to get rid of xslt processing.

Well, that's certainly not going to happen any time soon for our user
documentation. There are valid arguments to be made otherwise for API
references, but there's also a lot of non-API-reference documentation
that we need, and that we've started working on. And there are a lot
of advantages to pushing everything through a single well-maintained
tool chain.

Incidentally, the way g-ir-doctool is implemented, it's possible to
have different output formats. So if anybody wants to work on direct
HTML output (or DocBook or DITA or whatever else floats your boat),
you know where the code is.

Honestly, I think all of us (me included) are getting too hung up on
the tools. What we really need is better writing. No amount of tool
development is going to save you from a lack of good content.

--
Shaun