Re: jrb's help proposal

[Gregory Leblanc <gleblanc linuxweasel com>]

On Mon, 2001-09-03 at 06:04, Alexander Kirillov wrote:
> On Sun, 2001-09-02, Greg Leblanc  wrote:
> >> 3. We need to specify the name for top-level file for each application
> >>    (this is necessary to access the doc using "index scheme",
> >>    ghelp:appid). Traditionally, we used index.html for html and
> >>    <appid>.sgml for SGML. Maybe it is time to change this convention
> >>    and use index.[xml, sgml, html] for top-level file?
> >
> ><rant>
> >
> >Ick, this is a discusting suggestion.  :) I was frustrated enough
> >when Nautilus in GNOME 1.4 required us to rename some of our help
> >files.  I certainly do NOT want to have everything named "index".
> >We've already forced authors to make the ID on their top level
> >element "index", how much more are we going to twist their arms into?
> >Isn't having the docs installed into a common directory structure
> >($DATADIR/gnome/help/$APPNAME/$LOCALE/) good enough?  Even a
> >non-programmer like me can easily devise a way to determine which
> >file to display when the user requests the help document
> >"ghelp:appname".  I don't see any good reason to squash people into
> >using silly filenames.  </rant>
> 
> 
> OK. Assume the doc directory contais 2 files, usage.html and
> prefs.html. Which one do you load? What if the same words are in
> Italian (in it locale), or Russian? I do not believe it is easy to
> formalize... 

See, there you go with HTML cruft again.  I don't want to ship HTML.  If
we're just looking for XML files, not so tough.  Take a look at the
directory, find files that contain a <!DOCTYPE something ...> line, find
<something id="index">.  That's your file.  Once it's cached, not a
problem.

> I see only 3 possibilities: 
> 
>  a. We specify that the help browser *must* use scrollkeeper

Absolutely.  We've written the tool, we ought to be strong-arming people
into using it.  Plus, scrollkeeper performs acceptably on my 40MHz
SPARCstation 2, so if you complain about speed issues introduced by it,
it's time for a new computer.

>  b. We force the name for top-level doc file, same for each app

Meaning that you name it "appname.xml", as we've been doing for a while?

>  c  We abandon the scheme ghelp:appid altogether. 

Not a good solution.

	Greg