help and caching

[Sander Vesik <Sander Vesik Sun COM>]

So, somehow I got to be the one to write this up. 

------- % cut here & --------

There are presently problems with perfomance in displaying the help, it
brings about the need for the wraped chapter hacks and multiple .omf files
for them and there are equaly 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. Peopel 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 adminstrative 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 versiuons 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-rendended 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 perfomance 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 administrrtor 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