Re: New help format (regarding Yelp)

[Shaun McCance <shaunm gnome org>]

On Sat, 2004-02-14 at 06:18, Malcolm Tredinnick wrote:
> On Sat, 2004-02-14 at 22:40, Sridhar R wrote:
> > Yelp (gnome-help) currently uses XML for help formats.
> >  But the flaw in this is increased disk space. 
> > Consider a scenarion where help (xml) size is large
> > for an application.  
> > 
> > But if he uses single XML file for all help content,
> > the XML tags, when applied every section or every part
> > will increase the size.  
> > 
> > Furthermore, the help file is NOT compressed
> > 
> > Then, it is only a SINGLE xml document.
> > 
> > I suggest an alternative technique for help format.
> > Help files consists of
> > 
> >  * an index (or TOC) XML file that points to several
> > sections which are seperate XML files.
> >  * Now Compress the whole set of XML files.
> 
> This will be larger than just compressing the original single file.
> 
> My main problem with your reasoning is that you have not really argued
> convincingly that the small amount of space saved by compressing the
> files is worth the extra time we need to spend on uncompressing them
> when reading them. Popping up the help page after somebody hits "help"
> is something we want to do as fast as possible. If that means we blow an
> extra 10MB or so of disk space on the files (compressing all my help
> files did not save that much when I tried it just now), then that is
> hardly too large a price to pay.

Yes, agreed.  Note that I have written a GIOChannel to read bzip2 and
gzip compressed files automatically for the (non-existent) man and info
converters.  It would be a trivial task to hook this into the DocBook
converter, which I've considered doing before.  Given how little effort
that would take, it's probably worth it.  But only to give people the
choice to compress their help files.  I'm not sure I'd recommend that
applications install their help files compressed by default.

Of course, Sridhar is talking more about a structured tarball rather
than just compressing individual DocBook files.  This approach has been
taken by plenty of other systems, and there is some utility in it.  But
it does raise a lot of questions.  Would help bundles contain all the
translations, or would there be a bundle for each language?  How would
the bundle be able to interoperate with ScrollKeeper?

I'm not sure that the advantage of having a single downloadable file is
that important for the desktop help system.  Applications are going to
install their documentation at install time.  Documentation about your
system should be installed by your distro.  Basically any other kind of
documentation has an oppurtunity to be installed.

While I think it's a good idea to expand the focus of Yelp and the help
system to include more documentation, focus needs to remain on help for
things that are relevant to your system.  We shouldn't try to be some
generic document reader for any arbitrary document you download.  There
are plenty of other solutions people could use for that.

It is, however, possible that I'm completely overlooking some perfectly
valid utility for this.  If that's the case, then I really have to ask
that people make their suggestions in code, not in English.  There is
just way too much that needs to be done for me to spend time on this
sort of thing.

And, really, there wasn't much reason for this to be a reply to Malcolm,
except that my first sentence was "Yes, agreed."

--
Shaun