Re: Speed of processing man pages

On 4/15/06, Michael(tm) Smith <[email protected]> wrote:

> Anyway, setting up a system for on-the-fly generation of outbook
> from DocBook sources was not a particularly good idea. The process

You are right. My example was probably over-stretched.
(However, unfortunately, some people -- the developers of the GNOME help system)
are repeating this mistake ...)

> Is .36s * 10 really such an unreasonable amount of time to add to
> your build in order to generate docs for your application?

Oops, typo, I meant 100 instead of 10.  It's more of a fudge factor,
at the moment my sources aren't that big to require some 30 seconds to
process HTML,
but when they grow I woudn't want to have this problem.

> changes. A build setup the rebuilds the doc every time a code
> change is made is not a good build setup -- regardless of the
> system you are using for building your docs.

Yes, that's what I doing for my other project. Problem is,
DocBook is not really well-suited for "distributed documents" of this sort.

> Which is not to say that good DocBook-to-man converters aren't
> doing a lot of stuff themselves. I think I would personally say
> that any converter is doing quite a lot when it takes a large,
> complex DocBook document -- which is completely free from any
> presentational markup -- and transforms it into a rendering format
> (be is XSL-FO, HTML, groff, or whatever) that is primarily
> presentational.

Perhaps, but this "doing a lot of stuff" can, in theory at least,
be done quickly, as that instant tool shows.

> The ethereal-filter(4) man page, for example, is 4.2 megabytes.
ouch.
> perlfunc man page: 333K
> gcc-4.0.1 man page: 515K

Fair enough, I'll factored these in my tests.

> How reasonable would it be to expect to be able to convert the
> source for the 333K perfunc man page on the fly, and get a
> near-instantaneous response when doing it?

Okay, I think we got a little sidetracked with that example I proposed.
I'll retract my demand for near-instant transformation of arbitrary
DocBook documents.

> There are always going to be faster alternatives that XPath/XSLT.
> Some of them are fine alternatives, especially if you're willing
> to trade off flexibility and power for speed, and as long as you
> are willing to build your application in such as way that it
> requires end users to install additional dependencies (other than
> just an XSLT engine) in order to use it.

I don't like this stark binary choice we are giving to DocBook man page authors:

either use the DocBook man pages stylesheet, or docbook2X to get good output
and reasonable DocBook support

OR

use some crippled tool (instant) if you need it done faster

Can't we have our cake and eat it too? :)

> Good luck with that. I personally think that there are many better
> uses to which you could put your energy and skills than in trying
> to creating the world's fastest DocBook-to-man (or DocBook to
> HTML, or DocBook to FO transformation system).

I see. When I wrote the first message I never intended to take this to
the extremes, only to see if there
were smaller optimizations to docbook2X that could be done without
rewriting anything.
Unfortunately the answer is "not much",
but since I am the one who wrote docbook2X,
I am entitled to scathingly criticize my own work  :)

Anyway, I have a more complete summary in CVS: doc/perf.xml if you're
interested.

--
Steve Cheng
&#x912D;&#x541B;&#x535A;        http://gold-saucer.afraid.org


-------------------------------------------------------
This SF.Net email is sponsored by xPML, a groundbreaking scripting language
that extends applications into web and mobile media. Attend the live webcast
and join the prime developer group breaking into this new coding territory!
http://sel.as-us.falkag.net/sel?cmd=lnk&kid0944&bid$1720&dat1642