Re: GNOME ABI review

[Shaun McCance <shaunm wolfram com>]

On Wed, 2003-08-06 at 23:34, Havoc Pennington wrote:
> 9. Online Help
> 
>  How do you install it and how do you display it? 
>  Needs to be well-specified, well-documented, and kept working.

This is something that I've been thinking about a lot over the last few
weeks.  ScrollKeeper is a nice start, but it suffers quite a bit from
First System Syndrome.  Here's my thoughts:

Interoperability with KDE and other desktops is a MUST.  Third-party
application developers will want to stick their documentation somewhere
and have it viewable regardless of your desktop environment.  If they
have to jump through hoops to make their documentation work, then they
probably just won't do it.  Consequently, this whole discussion should
probably take place on freedesktop.org.

Using OMF files is a Good Thing.  Having to register them manually with
the system is a bit questionable.  It just begs for inconsistencies and
difficult upgrade paths.  It places more work on application developers
and packagers.  It makes it nearly impossible to provide alternative
implementations of the help system.

What are the reasons for registering?  Well, first of all, ScrollKeeper
generates a listing of all documentation on the system organized by
category.  I don't think it's necessary to generate a static category
listing.  Things like VFolers and the new Menu spec are figured out on
the fly.  More on this later.

Also, ScrollKeeper generates a couple of utility files for the document,
including a TOC and and index.  However, it only knows how to make them
for DocBook.  So if a help browser supports some other format, and it
wants to have a TOC, it has to implement it itself.  Furthermore, the
TOCs are problematic, because a help browser should have some degree of
choice in how it presents documents to the user.  I've had plenty of
problems with changing certain behaviors in Yelp because I have to rely
on these static TOC files.  (And, in fact, there are actually a number
of inconsistencies between Yelp's chunking and ScrollKeeper's TOCs that
I just couldn't get around.)

It turns out that TOCs are incredibly simple to construct.  I've been
working on some code that generates them with SAX, and it's pretty much
instantaneous for incredibly large docs (like Gnumeric's).

A more difficult issue is the index.  If it's just a matter of getting
and index for a single document, there's not much of an issue.  An index
can also be generated with SAX at parse-time very quickly.  However, it
would certainly be nice to have a master index of all docs installed on
the system.  I don't have a solution here just yet.

Back to the category thing.  ScrollKeeper adds the category attribute to
the subject element of OMF.  This is a heirarchy of pre-set categories. 
I'm not too fond of this.  For one thing, the category names are made
specific to KDE and GNOME.  So I won't see the documentation for KDE
programs in Yelp.  But if I'm a GNOME user, but I use KMail, I would
certainly like to see the KMail documentation in my help browser.

A possible solution is to use the Menu spec.  The category attribute
could be changed to provide a space-separated list of categories as
defined by the Menu spec.  Then the menu files could construct the
heirarchy for help files the same way they do for applications.  This
takes the actual heirarchy (an implementation detail, IMO) out of the
OMF files.

URLs are infinately problematic in our current system.  First of all,
the ghelp URL scheme is massive ad-hockery.  If a URL scheme is needed
at all, an intelligent one should be thought up and used by both KDE and
GNOME.  And it should be registered.  But I don't think we need to do
that.  The OMF files can provide any number of alternative URLs for a
particular document.  Thus, documents should be able to be identified by
a definitive URL (probably an http: URL), but then accessed by another
URL (probably a file: URL).  This would also help immensely in building
documents for the web.  A number of the GNOME docs have a ulink that
points to ghelp:fdl.  This works in Yelp, but fails miserably when HTML
files are generated for the web.

If a robust help system could be agreed upon by the different desktop
environments, then GNOME could get rid of the X-GNOME-DocPath extension
to .dekstop files, and KDE could get rid of the X-KDE-DocPath extension,
and a single DocPath key could be defined that will actually work.

A standard mechanism of providing rendering hints to the help browser
would be nice.  In my experience, it's pretty much impossible to do a
documentation build system that produces perfect output without manual
tweaking.  For instance, Yelp's chunking rules are rather sub-optimal
for quite a few documents.  A set of standard PIs would probably do the
trick quite nicely.  Hints, of course, should just be just that.  A help
browser should be able to display a document reasonably well without the
hints, and a document shouldn't rely on the help browser understanding
its hints.

Along similar lines, it would certainly be nice to provide generic XML
support.  DocBook is a nice format, but we shouldn't try to force every
piece of documentation into it.  If authors would like to use some other
format, it should be possible to do so.  Documentation in an arbitrary
XML format could ship with some default CSS.  Thus, if a help browser
has no inherant knowledge of a particular XML format, it can fall back
to the stylesheet shipped with the documentation.  Of course, this would
require us to have a generalized XML rendering component (GRE).

I probably have more things to say on the subject, but I can't remember
them at the moment.

--
Shaun