Shared documentation system

[Cornelius Schumacher]

On Monday 08 December 2003 01:10, Shaun McCance wrote:
>
> 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.

It's certainly good to have this discussion. I'm maintaining KHelpCenter 
and intended to suggest this discussion for quite a while now but never 
got around, so I'm glad you now took the initiative ;-)

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

KDE uses files following the Desktop Entry Standard containing meta 
information about the documentation which is shown in KHelpCenter. 
These files define the hierarchy of documentation and what documents 
are shown. There is special handling for KDE application documentation 
where the meta information is taken from the desktop files used for 
building the K-menu, for Scrollkeeper docs, man and info pages and some 
other stuff.

Finding and showing the actual documentation for KDE apps is done by the 
help-kioslave which knows about where the docs are installed.

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

Agreed. The other way around (showing GNOME docs in KHelpCenter) it's 
already possible to some degree, if the docs are using Scrollkeeper.

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

Yes, you are completely right. The desktop file approach of KHelpCenter 
already makes it quite easy to add 3rd party documentation. SUSE for 
example uses this mechanism to integrate the documentation of the 
complete distribution into the help center. It also provides an 
apache-based help browser for these docs using the same meta files as 
the KHelpCenter.

> 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 agree with all of these goals.

> What I'm proposing
> ------------------
> I would like to see something very similar to the way applications
> are registered.  Every piece of documentation would place a metadata
> file in a predetermined location.  Then the help browser would use
> something like the Menu spec to construct a listing of installed
> documentation.
>
> In fact, the applications Menu and the documentation Menu could
> probably even be merged.  Code that's constructing a menu of
> applications would ignore elements relating to documentation, and
> vice versa.  Doing this has the advantage that changing the
> organization of the applications automatically changes the
> organization of the documentation to match.
>
> As far as I know, this is similar to how KDE deals with documentation
> right now.  I want to make it more sophisticated.  Instead of using
> the DocPath field in .desktop files, I want to use a specialized file
> format that's capable of actually describing the document.  RDF/XML
> seems like a natural fit for this, except that it's a royal PITA.

You are right. That's similar to how KDE does it right now. It uses 
desktop files as meta information. For 3rd party apps it currently 
doesn't use the mechanism for creating the hierarchy as described in 
the Desktop Menu Specification but simply uses the directory structure 
of the meta files as hierarchy (including some .directory desktop files 
for describing the directories itself). It might be desirable to merge 
this in the future, so that the same mechanism is used for the menu and 
the docs for all documents.

I think your proposal makes perfect sense, but I would like to suggest a 
modification of the file format. Although RDF/XML certainly is a viable 
solution I think using desktop files has some advantages:

- It's consistent with the meta files used for creating the menu and 
could possibly even use the same files.
- Desktop files are simpler and faster to parse
- Desktop files are simpler to create

So my suggestion would be to come to a common desktop file definition 
based on the one currently used by KHelpCenter and use this as meta 
information for the desktop help systems. The current definition is 
quite generic and contains fields for (translated) summaries and 
descriptions, information how to search the doc and some special 
information (e.g for integrating man and info pages). Hierarchy is 
reflected by hierarchy of the meta files.

If there is interest I could post a more detailed description of the 
meta information KHelpCenter uses right now. It's similar to what you 
suggested to put into the XML files.

-- 
Cornelius Schumacher <schumacher at kde.org>