Re: jrb's help proposal

[Alexander Kirillov <kirillov math sunysb edu>]

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... 

I see only 3 possibilities: 

 a. We specify that the help browser *must* use scrollkeeper
 b. We force the name for top-level doc file, same for each app
 c  We abandon the scheme ghelp:appid altogether. 



As for twisting arms... I, as doc writer, do not consider forcing file
names "arms twisting" (after all, no one complains that man pages have
same filename as the binary). But if someone is really sensitive here,
why not name your files whatever you like and have index.[html,
xml,...] symlink to the top-level doc? Seems reasonable to me. 

Sasha