Re: Speed of processing man pages

Steve Cheng <[email protected]> writes:

> On 4/15/06, Michael(tm) Smith <[email protected]> wrote:
> 
> > 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.

No, the instant tool doesn't show that. I bet that you could
easily create a DocBook-to-man tool just as fast as
instant/docbook-to-man if you took the approach that it does --
which is to say, just pretend a lot of the difficult-to-process
stuff (tables, footnotes, proper *info handling) doesn't exist and
instead simply transform the source strictly in document order and
output it that way -- which ignores the fact that there are cases
where you need to output in a different order than the document
order in the source.

The docbook-to-man design severely limits what it can do, and so
also severely limits what users can do. When users find that it
docbook-to-man doesn't output their source the way they would
expect, they have to make changes to their source to work around
the deficiencies in docbook-to-man.

I think the main design criteria for any tool for transforming
DocBook to output formats is that is should handle any structures
that DocBook says are valid, and output them as expected. Most
users could not care less about how fast a tool is if it does not
give them the output they expect.

> 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? :)

I think you already have. DocBook2X is plenty fast enough for most
users. And how much faster would you reasonably expect that you
could make it? I think you would have a difficult (or impossible)
time making it even just twice as fast. But let's imagine that you
could make it three times as fast. Even if you were able to
somehow make it that fast, it would still not seem anywhere near
fast enough to the people who are choosing to use docbook-to-man
now instead of DocBook2X or the DocBook XSL stylesheets.

> > 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",

I am sure there are some optimizations you could make. It's just a
matter how much work it'd be to implement them and how much of
priority your users would place on having some moderate
performance increases instead of having, say, more features or
support for more DocBook structures.

> but since I am the one who wrote docbook2X,
> I am entitled to scathingly criticize my own work  :)

And I'm obligated to let you know what my view is as a user and
fellow developer (well, hack developer in my case...) And that
view is: I think you've done a nice piece of work in putting
together DocBook2X. I can understand that as an engineer maybe you
can here and there see some flaws in your design and would love to
fix those and to make your application as efficient as possible.
But sometimes you need to step back and look at everything you've
done well already, and carefully consider what value your users
see in your application as it currently is, and what potential
improvements in it would be most important to them.

When I took over maintenance on the DocBook project manpages
stylesheet about a year ago, my goal was to put together a pure
XSLT DocBook-to-man processor that worked as well as DocBook2X.
That remains my goal. If I had never seen or used DocBook2X, I
would never have bothered setting out on the mission of improving
the manpages stylesheet -- because to me, DocBook2X proved that it
was possible to create a reasonably full-featured DocBook-to-man
processor, with acceptable performance.

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

Cool. And I reckon I'll also go ahead and install the new release
and try it out.

  --Mike