Re: jrb's help proposal

[Alexander Kirillov <kirillov math sunysb edu>]

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. 

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

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?

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.


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. 


 
------------------------------

Footnote: [1] In fact, not much functionality is lost. Table of
  contents and index can be built from XML source at installation
  time.  We do lose keyword search capabilities, but I'd trade that
  for speed any day. Why are we so obsessed with shipping the docs in
  source (xml) form? Clearly, in the future this is the way to go -
  when mozilla/Nautilus/whatever can show them as fast as html. But
  now?