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

[Frans Englich]

On Tuesday 31 October 2006 16:51, Don Scorgie wrote:
> Hi,
>
> I'm forwarding this to the xdg list as recommended.

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.


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.


Cheers,

		Frans
-------------- next part --------------
A non-text attachment was scrubbed...
Name: help-spec-0.1.5.xhtml.bz2
Type: application/x-bzip2
Size: 11218 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/xdg/attachments/20061031/6c7d368f/attachment.bin