Shared documentation system
schumacher at kde.org
Mon Dec 8 06:51:54 EET 2003
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
> 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
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
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
> 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
> * 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
> * 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
> 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>
More information about the xdg