jrb's help proposal (was Re: Undelivered ...)

[John Fleck <jfleck inkstain net>]

Jonathan -
First, thanks for doing this. It looks excellent.

On Fri, Aug 31, 2001 at 08:40:49PM -0400, Jonathan Blandford wrote:
[snip]
> OVERVIEW:
> =========
> 
>  * Have installation of xml as the main supported format, with
>    scrollkeeper supplying metadata

This means a move to DocBook 4.x XML for GNOME 2. I think this is the
right thing to do. Converting old sgml documents is relatively
straightforward, and the libxslt tools work well. It does mean we need to
work out the details of the tool chain for producing HTML, postscript, etc.

>  * Allow installation in places other than where GNOME is installed
>  * Allow applications to install HTML as a fall back

Will we courageously abandon shipping HTML as part of standard GNOME
packages and only ship the XML? I think the answer should be yes.

>  * Allow applications to show system help as well as
>    application-specific help
>  * Define ghelp URI scheme
>  * Have generic method of launching the help system
>  * Define a simple API -- 3 functions.
>  * Assume that the help-browser links with the same gnome-libs that the
>    app links with -- or at least the same prefix.
> 
[snip]
>   2) The relative ghelp URI scheme:
> 
>   The basic form of the relative URI scheme is:
> 
>                      ghelp:<appid>/<file>[?<query>]
> 
>   In general, this form can be turned into an absolute scheme with a
>   little work on the help browser's part.  The primary use of a relative
>   URI is for cleanliness of URI so that the user could enter it by hand.
>   It also gives you a language independent way of referring to a
>   document.
> 
>   2.1) The <appid>
> 
>     The appid is the id of the application and the location of the help
>     files.
> 
>   2.2) The <file>
> 
>     The file listed here is a little different from the absolute URI
>     scheme as the extention is optional.  The help browser is expected
>     to try appending ".xml", ".sgml", and ".html", when looking for the
>     file before falling back to <file> without the extention.
> 
>   2.3) The <query>
> 
>     Identical to the <query> in 1.1
> 

So if I am writing documentation for app1 and I want to create a link
within it to a particular section in app2's documentation with
id="thesection", I would use as my ulink URI:

ghelp:app2/app2.xml?thesection

Do I have this right? Or would it be:

ghelp:app2?thesection



>   2.4) Converting a relative ghelp URI to an absolute URI:
> 
>     To convert URI schemes, the help browser must convert the
>     <appid>/<file> part to the <path> field.  The basic way of doing this
>     is to do
>     <path> = <GNOME_DATADIR>/<appid>/<LOCALE>/<file>[<extention>]
> 
> 
>     where <GNOME_DATADIR> is the datadir prefix where the
>     help-browser/GNOME is installed and <LOCALE> is the current locale.
> 
>     extension = ( ".xml" | ".sgml" | ".html" | "")
> 
>     An interesting thing about doing the conversion is that it requires
>     the application doing the conversion to check to see if the file
>     exists.
> 

To read KDE's docs, I believe we need to ad .docbook to the extension list.

[snip]

> PART 4: IMPLEMENTING THE HELP BROWSER:
> ======================================
> 
> The help browser must implement the following things:
> 
>  * support showing both relative and absolute ghelp URI's
> 
>  * be able to display docbook xml and HTML
> 
> Additionally, the following would be nice:
> 
>  * scrollkeeper support to generate an index of topics, and support
>    of index ghelp URIs.
> 

By "index of topics" do you mean a Nautilus-style
ScrollKeeper-generated list of available help docs?

 
> TODO:
> =====
> 
>  * I'm not sure at all about the name 'ghelp' for the URI scheme.
>    Perhaps 'gnome-help' would be better.  Then again, the gnu project
>    seems to have taken over the world-wide 'g' namespace.
> 
>  * We use '?' to go to a section id in the URI scheme.  Would '#' be
>    better?
> 
>  * Write API documentation for the 3 functions.
> 
> 
> FOOTNOTES:
> ==========
> 
> [1] More information on actually writing the documentation can be found
> at http://developer.gnome.org/projects/doc/  FIXME: need better link

http://developer.gnome.org/projects/gdp/styleguide.html
for the style guide, and
http://developer.gnome.org/projects/gdp/handbook.html
for the GDP handbook.

Again, thanks for this, Jonathan.

Cheers,
-- 
John Fleck
jfleck inkstain net (h), http://www.inkstain.net/fleck/