Shared documentation system

[Magnus Bergman]

On Sun, 07 Dec 2003 18:10:08 -0600
Shaun McCance <shaunm at gnome.org> wrote:

> NOTE:  A shorter version of this email is stuck in moderation, because
> I'm a doofus and was subscribed with the wrong email address. 
> Normally I'd wait for the moderators, but I had stuff to add.
> 
> I'd like to get some discussion started about having a shared system
> for documentation in GNOME, KDE, and other desktop environments.  I am
> the maintainer of Yelp, the GNOME help browser.  The current stable
> version of Yelp finds documentation through ScrollKeeper.  As far as I
> can tell,the KDE Help Center uses the DocPath field of .dekstop files,
> and all documentation is installed in
> 
> <prefix>/doc/HTML/<lang>/<app>
> 
> That's mostly a guess on my part, based on what I see in KDE 3.1.  If
> I'm wrong or out of date, feel free to smack me.  The KDE Help Center
> also seems able to read from ScrollKeeper, but it's not used as the
> primary means of installing documentation for KDE applications.
> 
> Why we need a shared system
> ---------------------------
> It's my observation that only core GNOME apps use the GNOME help
> system(even though ScrollKeeper is supposed to be neutral), and only
> core KDE apps use the KDE help system.  This is a problem.  If I'm
> using KMail inside of GNOME, I should still be able to view KMail's
> documentation.
> 
> In the case of mixing applications from different desktops, the proble
> misn't devastating.  Most users will get the help for an application
> by selecting it from the Help menu.  In KMail, that will open up the
> KDE Help Center.  In Evolution, that will open up Yelp.
> 
> This presents a problem for third-party software, though.  When ISVs
> develop documentation for their applications, what do they do?  If
> they have to jump through hoops to make it work with different
> desktops, then they probably just won't bother.  They'll put it in
> HTML and open a webbrowser.
> 
> Goals of the help system
> ------------------------
> * Users should be able to choose the help browser of their choice.  If
> I'm a GNOME user, I should be able to see all my documentation in
> Yelp. If I'm a KDE user, I should be able to see all my documentation
> in the KDE Help Center.
> 
> * The help system should impose as little policy as possible on the
> help browser, and should expose as little policy as possible to
> documenters.
> 
> * It should be simple to place a document in the help system.  The
> help system shouldn't require anything to be run to register or
> unregister a document.  That just begs for problems.
> 
> * The help system should not assume anything about the viewing
> program. The viewer may not be a graphical program like Yelp or the
> KDE Help Center.  It may be a print system, a console program, or some
> sort of documentation server.
> 
> * Documents should be able to supply meaningful metadata, which hel
> pviewers may be able to use.  The metadata format for documents should
> be easily extended in a well-defined way.
> 
> * Applications should have a simple and consistent way of accessing
> their documentation, independant of the desktop environment.
> 
> * Documents shoud have a simple and consistent way of referencing
> other pieces of documentation, independant of the desktop environment.
> 
> * The help system should be capable of pulling information from other
> existing help systems.  This way we can have legacy compatibility with
> KDE's and GNOME's current systems.  Also, this can provide a
> consistent means for help viewers to integrate man and info, if they
> choose to.

I totally agree that all those goals are very important. I believe this
proposal take them all in account. There are two major things that needs
to be included in the standard:

1: How applications launch the help reader to display the right help
   document.

2: How the help viewer can find the document and in what format it
   should be in.

For (1) I suggest that applications invoke "helpview <domain>
[<section>]", where "domain" usually is the name of the applcation and
"section" is a way to optionally go to a specific part of the
documentation.

For (2) there are already fully usable solutions (like man and info),
but apparently that is not enough. I suggest that we just agree on one
place in the file system where the files should be placed (for example 
"<prefix>/doc/HTML/<lang>/<domain>"). And keep just that as the minimum
requirement. Then have optional extensions for supplying meta data. I
see no reason why this meta data cannot just be a part of the
document.

Then there is the task of designing the help viewer(s), but that can be
done in just any way, as long as it knows about these two simple things?

Does it have to be more complicated than that?