Re: yelp performance (Re: Successor to DocBook)

[Shaun McCance <shaunm gnome org>]

On Fri, 2006-07-14 at 09:44 +0200, Karl Eichwalder wrote:
> > I can tell you that most of the worst bottlenecks
> > are caused by complexities inherant in DocBook.
> > For instance, converting CALS tables to HTML is
> > pretty insane in XSLT.  Automatic numbering takes
> > its toll.  Getting internationalization right is
> > a speed bump.
> 
> That's why I recommend not to feed untouched XML files into the help
> system.  XML is okay, but transformed for better performance.  Also
> there should no need for yelp to validate the files (I'm not sure
> whether it actually does validation); validation should happen at
> installation time.

Yelp does not validate documents at runtime.  Currently,
gnome-doc-utils validates documents on 'make check'.
I have considered validating on make, but we'd have to
use some sort of hackish stamp files to prevent it from
revalidating all the time.  People should be building
tarballs with 'make distcheck' anyway.  Validating at
installation time seems like a good idea.

I'm not a big fan of installing cooked documents, though
I have recommended it in a few select cases in the past,
when I simply couldn't address the performance concerns
well enough, or when they application's developers were
not requiring a newish Gnome, and so had to worry about
older Yelps.  (I can't change the past.)

The problem with installing cooked documents is that
the user is stuck with the presentation you went with
when you created the HTML (or whatever else you turned
it into).

For example, Yelp uses colors in various places.  I'm
not completely happy with the colors it's using right
now, but they're better than nothing.  They make the
document more vibrant and easier to read.  The colors
Yelp uses are computed directly from the theme.  Are
vision problems forcing you to use a high contrast
inverse theme?  Hey, Yelp has you covered.

A great example of how cooked documents limit what
you can do is Texinfo.  Texinfo source files are very
nicely structured, with a reasonably sane markup.  We
could make some really nice HTML displays from those
source files.  But the source files aren't installed.
Instead, they're compiled to info files, reduced to
the level of what can be displayed on a VT100.  As a
result, our HTML display of info is pretty crappy.

(As an aside, I often call Texinfo a great idea, done
poorly.  It got a lot of things right, but a number of
design decisions (flaws in my book, maybe not others'
books) have relegated it to the niche geek tool it is
today.  Done differently, I believe Texinfo could have
become the single documentation format for everything,
including the desktop.)

--
Shaun