Re: jrb's help proposal

[Mikael Hallendal <micke codefactory se>]

2001-09-02 klockan 21.00 skrev Alexander Kirillov:

Hi!

> 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'm not sure what you mean here. That every document should be installed
in both HTML _and_ DocBook formats? This sounds like a real waste of
space...

I think we should either use SGML _or_ HTML and I think we could
probably use either without loosing functionality if we improve our
tools. (see below).

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

I think it's important that every help browser should behave the same
way. That if you use one you get the same information as in another one.
Most users that will make heavy use of a help browser will not be
experienced users and might be confused why they all of a sudden lost
lots of information (ie because they installed a helpbrowser that don't
support ScrollKeeper).

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

What do you mean by keyword search capabilities and index? 
We need to agree on what those terms are used for. I'd say you use the
keywords to build the index. Doesn't make sense above though :)

Anyway, if our sgml->html tools were able to extract that information
and store it in the same xml-file as the TOC we should be able to have
keyword search with a html-only system.

I'm not sure about this, but jborg are looking at the possibility to
make gtkhtml2 render docbook directly using libxslt without first
convert it to HTML. 

I really think we want to be able to search among keywords, it's really
helpful when you are not sure what you are looking for. In the future we
also want to be able to do full text searches among all documents (we
would then have to build an search database at install time).

Regards,
  Mikael Hallendal

-- 
Mikael Hallendal                micke codefactory se
CodeFactory AB                  http://www.codefactory.se/
Office: +46 (0)8 587 583 05     Cell: +46 (0)709 718 918