Re: Standardizing help paths

[jg pa dec com (Jim Gettys)]

> From: Miguel de Icaza <miguel@gnu.org>
> Date: Sat, 6 Nov 1999 08:59:08 -0600
> To: sopwith@redhat.com, jg@pa.dec.com
> Cc: gnome-doc-list@gnome.org
> Subject: Re: Standardizing help paths
> -----
> On the magic "ghelp" url:
> 
> > I've started doing a little bit of work on the Gnome help subsystem. I'd
> > like to come up with a standard way of referring to a help
> > page/entry/whatever. ghelp: is a really bad hack (it's not a protocol,
> > daggone it!).
> 
> The "ghelp:" prefix (or the http, ftp) are not intended to be
> "protocol" selectors, but the beginning of a universal resource
> identifier.
> 
> I hope Jim can help us coming up with a nice scheme, it seems your
> proposed scheme is just reinventing things that have already been
> invented.

I presume you mean me...

There are a number of issues here: how you refer to it in your
documents (the source of the help), and how it is named in an application.

I believe strongly we need to leverage relative URI's: this
implies, for example, that the string "ghelp:" never appear in help
sources.

Why, you might ask:

Well, here's a simple argument that I hope convinces you:

You'd like the identical help documents to be available either in
the file system or via an HTTP server, for example.  It is infeasible
to have to rewrite the documents to have to move them from gnome's
help system to a web server.

So you'd better not have http or ghelp strings present in any
gnome document (unless, in the case of http, you really need to
reference a web site).

It turns out that there are similar concerns for EACH and EVERY
piece of URI syntax (e.g. ":", "//", "/", "#"); you have to be very
careful not to try to use these syntactic forms to mean other
semantic things than they do in generic URI's, or you have problems
serving the same content up under different schemes.

So there are a number of traps for the unwary...

Fundamentally, therefore, it is a naming heirarchy that has to work
well, and due to the observation above, needs to be independent of
access scheme.


If I have time (not clear at the moment; I have two kids with strep this 
instant), I'll spend a bit of time looking at how gnome help currently 
works and see if I can make some more concrete suggestions.  Ping me
in a week if you haven't heard more from me.
				- Jim