Perhaps use OASIS Catalogs? [was Re: Help System Spec]

[Don Scorgie]

Hi,

I'll preface all the comments by stating that the spec was originally
written by others.  My meagre contribution amounted to adding the
"Additional Sections" (section 5.4), the examples and "Joint System
Proposal", the many notes scattered throughout and correcting any
glaring spelling mistakes.  This has the advantage of shifting the blame
away from me :)  It will also explain why my comments are what they are.

On Tue, 2006-10-31 at 21:31 +0100, Frans Englich wrote:
> On Tuesday 31 October 2006 16:51, Don Scorgie wrote:
> 
> As you know, this is interesting and needed work.

:)

> 
> OSDL has also been looking into improving documentation interoperability. 
> Perhaps these two projects should be merged so we can solve two problems in 
> one blow. Here's some background(see comments for IRC log, and links):
> 
> http://englich.wordpress.com/2006/10/17/open-source-documentation-framework/
> 
> > A little while ago, Cornelius Schumacher sent me an old draft of a spec
> > for a joint help system between GNOME and KDE.  Since then, I've been
> > looking through, adapting it slightly and adding various bits needed by
> > GNOME [1].
> >
> > I feel its in something approaching a decent state (well, enough for
> > people to look over and comment on), so I'm not attaching it to this
> > email.  Instead, you can get it from [2].  It's in docbook format, so
> > you can view it in you're favourite help browser at you're leisure.
> 
> Attached is a XHTML rendering for those not into Docbook(extract with 
> bunzip2).
> 
> > You will notice a lot of Note boxes within the file.  In these cases,
> > they're where I wasn't sure about something, wanted to add some thoughts
> > (but didn't seem to fit properly) or I got bored and wrote garbage ;)
> >
> > Hopefully, this won't disappear into the ether and instead something
> > will come of it.  Any feedback and comments much appreciated.
> 
> I did one quick read-through and here's my quick comments(will send separate 
> mails).
> 
> According to my opinion the spec is in general vague and have editorial 
> issues(about one on average in each paragraph), as typical for Free Desktop 
> specifications. But that's quite expected considering it's early in the 
> development process. So, it will need a rewrite when that time comes.

Yep, early draft.

> 
> 
> A significant size of the spec is spent on a mapping/URI-resolver system(which 
> I don't fully get yet). My initial reaction is that it would be a gigantic 
> improvement to use OASIS XML Catalogs here:
> 
> 1. Installed catalogs would be registered with the help system
> 2. The help system computes an URI that identifies the topic of interest
> 3. The help system resolves this URI through the catalogs for a URI to 
> dereference for a physical resource for user consumption.
> 
> It would re-use a powerful, generic, implemented, well-spec'd mechanism that 
> provides all one needs for mapping URIs.

My personal opinion is that user-facing XML sucks.  The files are
intended to be edited by doc writers.  Doc writers already deal with
docbook / XML.  We shouldn't lumping more on them (especially when the
XML flavour is different).  Just my personal opinion.

In addition, the other freedesktop specs use the keyfile format
(.desktop files for example).  We should remain consistent.

> It's not defined why DocSearchEnabledDefault should be used, so it's
> unusable 
> as is. That is, can the user use that key without taking a particular 
> implementation into account? Doesn't look like so from my reading.
> 
> My gut feeling is that it should be left out. Either that, or 
> define "searching". Something I wouldn't like to do ;-)
> 
> Here the problems with that Desktop files didn't re-use XML shines
> through: 
> with XML it would be possible to specify custom keys in an
> interoperable way. 
> For example, search hints for a specific implementation could be
> supplied.

Yep.  I was pretty blurry on what exactly this did.  Again, my personal
opinion is that any searching should search anything it can (and allow
the user to reduce the search criteria as desired).  I think the
DocSearchEnabledDefault should be left out.

We do have hints for how search should be done - the mime type
(DocType).  It's up to the help app to determine if it can search that
doc type.

> The specification use URI schemes(it doesn't define what they mean or
> should 
> be treated, so in either case it needs to be rewritten) that aren't
> valid, 
> which in my opinion is a no go.
> 
> For example, the "help" scheme is not registered, and there's nothing
> that 
> prevents me from writing a spec after I've finished this mail that 
> defines "help" in another way. For a discussion of this problem, 
> see(especially the comments are useful):
> 
>         http://englich.wordpress.com/2006/10/13/kdes-uris/
> 
> I see here an opportunity to break KDE's trend of using proprietary
> schemes. I 
> think this is especially important in this case since it is the
> intention of 
> the help system to be interoperable.
> 
> I think fixing this is easy. Since it's not required that the URIs
> must be 
> exposed to users, they can read in anyway.

Currently, we (GNOME) use ghelp: for our URI [1](which is used to find
the document within our current metadata framework).  The "help:" uri is
intended to provide a default location for help files within the
metadata file.  This is one of the areas I considered removing.  The
gratuitous use of custom URI's is bad (IMO).  I came up with several
other objections (about installing the help file in a non-standard
location.  In which case, any metadata with help: uri is going to
break), but in the end, decided to leave it in for now.  Another point
I'd be glad to remove.

Thanks
Don

[1] E.g calling 'yelp ghelp:zenity' from the command line will search
scrollkeeper for the document who's filename is 'zenity.xml'