Re: [docbook-apps] Refentry, man pages, and DocBook XSL 1.69.0

[Peter Karman <karman@cray.com>]

Michael Smith scribbled on 7/22/05 7:45 AM:

> I realize the stylesheet is relatively slow, but I'm interested in
> know just how slow. Can you comment on the following?
> 
>   - your total build time with the manpages stylesheet versus your
>     build time with docbook-to-man

http://docs.cray.com/man/CCm/54/cat1/CC.1.html

the catman version builds in 2-3 seconds with docbook-to-man (including 
formatting with groff). With XSL, it's more like 7-9 seconds.

> 
>   - how many Refentry instances you're processing during each build
> 

An entire operating system's worth: 1000+ pages. Plus our programming 
environment, which is another 800+ pages. And that's for each release. I have 
over 10,000 XML man pages in src right now, any subset of which I might have to 
rebuild for one reason or another.


>   - what XSLT engine you use

xsltproc


> 
> Anyway, I should tell you that speed optimization is not a primary
> design goal of the manpages stylesheet, or of the DocBook XSL
> stylesheets in general. If speed is a high priority for you, I
> think that, in general, using XSL is not the best way to go, and
> in particular, using the DocBook XSL stylesheets isn't.

for man pages, speed is pretty important for us, just in terms of our volume.


[...]

> So I do not think the manpages stylesheet is excessively slow
> relative to generating a different output format for the same
> document via XSLT.
> 

I agree with you. We've used Jade/DSSSL for several years to do HTML output for 
our software manuals, and xsltproc/XSL is faster. But not exceedingly so.

For man pages, our volume is so much higher (the ratio is something like 100 man 
pages for every book) that speed becomes an issue.

> However, I can understand it being much slower than a solution
> such as docbook-to-man that does not use XSLT. I very much doubt
> that no matter what speed optimizations I tried to implement, the
> manpages stylesheet would ever end up coming anywhere close to
> being able to generate output as quickly as a non-XSLT solution.
> 

and that's cool. Like I said, we're doing 100s of pages at a go, and that's a 
different scenario than for a OSS project doing a dozen pages.

FWIW, Sun has a situation much like ours (Solaris man pages are largely in 
SGML), and they actually ship docbook-to-man as part of the Solaris OS. Their 
sgml2roff script is a modified docbook-to-man.sh. And since Sun ships the SGML 
source on the Sun boxes, the conversion process is actually done on the fly. So 
it has to be fast.

> [3] For example, in the simplest case, if you are processing a
>     single man page, and it only takes less than 2 seconds to
>     process it with docbook-to-man, and 5 to 7 seconds to process
>     it with the manpages stylesheet, it's not such a big deal. But
>     if you are processing 100 man pages and it takes 3 or 4
>     minutes to process them, instead of 1 minute, it matters.

exactly.

Thanks.
-- 

Peter Karman  .  http://docs.cray.com/  .  karman@cray.com

"I love deadlines. I love the whooshing sound they make as they go by."
                        - Douglas Adams