Re: help and caching

[Eric Baudais <baudais kkpsi org>]

Sander-

I like this proposal a lot.  I think this would allow us to only process
and cache the bits of the docs the user requests.  This would cut down
on load time and improve performance.

My objection to this is we should not be using Yelp, a help browser, to
pre-generate the documents.  I think this should be in libgnome or some
other place which is already dependent on libxml2.  Yelp should just
contain the browser and stylesheet portions of the help system.  Yelp
should not contain tools and utilities to process the GNOME docs.  Maybe
this utility could be integrated with a docs build package.

Eric Baudais

On Wed, 2002-06-12 at 18:22, Sander Vesik wrote:
> 
> So, somehow I got to be the one to write this up. 
> 
> ------- % cut here & --------
> 
> There are presently problems with performance in displaying the help, it
> brings about the need for the wrapped chapter hacks and multiple .omf files
> for them and there are equally many and bad problems with several
> alternatives:
> 
> 	* it would not be good to go back from "online" rendered xml
> 	  documents. We would lose scrollkeeper integration, docs would
> 	  not get "built"/would get out of date, and localised docs might
> 	  not get build/included in all cases. People building their own
> 	  packages have to get the doc build tools right, etc.
> 
> 	* a per-user cache residing in a user's home directory would need
> 	  to be very constrained in space and there would probably need to
> 	  be an option to turn it off, and thus its value due to cache
> 	  overruns would be low
> 
> 	* a per-system updated cache would need a setuid program, brings
> 	  about yet another set of administrative preferences, and is a
> 	  potential bad source of security issues
> 
> 	* most caching and pre-generation schemes don't allow for a
> 	  simple way to update the docs when newer versions of the
> 	  help system/stylesheets are available. 
> 
> Thus the following proposal:
> 
> 	share/gnome/help/$docname/$locale/
> 
> would continue to contain the master versions of documents
> 
> 	share/gnome/help-generated/$docname/$locale
> 
> would contain the pre-rendered document "fragments" in the form of
> sectid.html, which would be used if help is requested for that particular
> doc/locale combination (falling back to C) *if* the timestamp on the file
> is newer than that of the xml document and the stylesheet.
> 
> 	yelp-pregenerate docname locale
> 
> would generate the pre-generated html for the specified doc and locale.
> 
> It would get rid of the performance problems with large documents, avoid
> problems when users install a newer version of the program (they would
> just get the help displayed from the xml version), allows distributors to
> ship optional 'doc-accelerator' packs or do the generation at installation
> time, allows for simple space/speed tradeoffs with docs with localisations
> to seldom-used locales, etc. It also avoids having to deal with security
> issues.
> 
> The main downside is that users in large installations are at the mercy
> of the system administrator in yet another way. 
> 
> ------ % cut here % -----
> 
> Mainly to kick off the discussion.
> 
> 	Sander
> 
> 	you'll rescue me right?
> 	in the exact same way that they never did
> 	i'll be happy right?
> 	when your healing powers kick in
> 
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list
>