Re: jrb's help proposal

[Gregory Leblanc <gleblanc linuxweasel com>]

On Sun, 2001-09-02 at 14:00, Alexander Kirillov wrote:
> 
> Some more comments:
> 
> 1. We need to make sure that links between HTML files (e.g., in file
>    "intro.html" a link to <a href="prefs.html#colors">) work,
>    regardless of how the original file was loaded (i.e., even if it
>    was loaded using the scheme ghelp:<appid>?intro). Of course, this
>    is responsibility of help browser, but I remember we had problems
>    with this before, with early versions of Nautilus. So maybe, add
>    this to "Implementing help browser" section. 

Right, this will be required so that apps which ship HTML help work.  

> 2. Jonathan's suggestion says that the docs must use <!DOCTYPE article ...>
>    Most documents - yes. But some large docs need to  use <!DOCTYPE book >
>    instead, and maybe some small ones (individual applets/capplets?)
>    may use <!DOCTYPE sect1 >? I am not sure about the last one...

The requirement here is that our docs should be using DocBook 4 XML, not
that they're a specific top level element.  

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

> 4. Section "application help" specifies that applications should
>    install docs in DocBook/XML format. My suggestion: mention
>    explicitly that apps may include docs in HTML format.
>    
>    In fact: I strongly feel that every app *must* include docs in HTML
>    format (here I disagree with jfleck) It may be built from XML at
>    installation time, so this does not make packages any larger. My
>    reasoning: on my system, sgml->html conversion (gnome-db2html2)
>    is still rather slow. I'd much prefer that the help browser
>    displays pre-built HTML, even if it means that some of the
>    functionality is lost [1]. From the discussion we had here before,
>    many people share my point of view. So I think we should give this
>    freedom to users. Or we should implement cacheing as suggested by
>    jfleck.

I'd rather not ship HTML in the packages.  I'm using libxslt on a daily
basis, and I've got some concerns about it's ability to perform
satisfactory on-the-fly transformations.  I think that the best solution
here is going to be a caching mechanism, but I can't say for sure.

> 5. Related to the previous one: part "implementing the help browser"
>    says 
>   
>    Help browser must be able to display Docbook XML and HTML
> 
>    I believe there is room for lightweight help browser that only
>    displays HTML, but is fast. Maybe: have "fully compatible help
>    browser:" supports Scrollkeeper and XML; "partially compatible:"
>    supports "ghelp:" URI (w/o using Scrollkeeper) and HTML. 

So let me make sure that I'm understanding, as this is a bit garbled.
Fully compatible  ==  uses scrollkeeper, ghelp uri, xml formated docs
partly compatible ==  supports the ghelp uri

I don't want to ship HTML docs, which makes the "partly compatible" more
dificult, don't you think?  It'd be straighforward if the DocBook to
HTML conversion was done "behind the scenes", but it doesn't sound like
we're going to be able to do that.
	Greg