Re: Proposal for GNOME-2.0 help system

[Jonathan Blandford <jrb redhat com>]

Alexander Kirillov <kirillov math sunysb edu> writes:

> I have some problems with Jonathan's suggestions. Assume I want to see
> docs for gnotravex. What URI I should enter in help browser?
> 
>  Natural choice would be "ghelp:gnotravex". But according to the
>  suggested API, support of this form of URI is optional, so help
>  browser may not understand this. 

The rationale for making it optional is that users would only ever enter
it in a help browser.  I wanted to lower the barrier for writing a
help browser -- that's all.  However, your suggestion below is
reasonable too.

>  I could enter the "relative URI": gnotravex/filename. But what file
>  name to use? If it has docs in xml/sgml format, then it should be 
>   gnotravex/gnotravex[.xml, .sgml]

The relative uri is just a prettier URI to display.  I think some uri's
may be guessable (like ghelp:AisleRiot2/Odessa) while others
(gnotravex/prefs) are more obscure.  I just want to avoid the full URI
where possible.

> It becomes even worse for crosslinking between docs. At the moment, we
> use <ulink url="ghelp:appid">; again, since the support of this scheme
> is optional, we can not rely on it. 

Good point.  Okay -- we'll make it mandatory

> --------------
> Support of "index" scheme (ghelp:appid) is mandatory. Ideally, it
> should be resolved using Scrollkeeper; this is optional. If not, help
> browser must be able to translate it to absolute URI like 
> 
> <path> = <GNOME_DATADIR>/<appid>/<LOCALE>/<file>
> 
>  trying for <file> "appid.xml", "appid.sgml", "index.html" - in this order.
> --------------

I'll add it to my draft.

> And finally: maybe it would be a good idea to try supporting KDE docs,
> too - maybe we could talk to them and allow for URIs "khelp:"? 

Sure.  Do we know how their URI scheme works?

-Jonathan