Shared documentation system

Cornelius Schumacher schumacher at
Thu Dec 11 18:15:43 EET 2003

On Monday 08 December 2003 08:44, Shaun McCance wrote:
> On Sun, 2003-12-07 at 22:51, Cornelius Schumacher wrote:
> > On Monday 08 December 2003 01:10, Shaun McCance wrote:
> [snip]
> > > 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.
> Oh certainly.  It's not that nobody can use these systems.  It's not all
> that difficult to stick something in ScrollKeeper either.  But for one
> reason or another, people don't use them as much as they could.  Right
> now I'm using Fedora Core 1.  Fedora has a ton of documentation, but
> none if it is in ScrollKeeper.

Using Scrollkeeper is quite complex for developers, especially for packaging. 
I suppose if the same effect can be achieved with a simple hand-written file 
which doesn't add any new dependencies to the package adding meta information 
for documentation would have a chance of wider acceptance.

> So if there's a common system, it's just that much easier for people to
> get their documentation to show up.  And hopefully it would also mean we
> have more people behind the system, and thus more people to smack others
> when they don't register their documents with the help system.

Agreed, I'm very much in favor of a common system.

> I think it's very beneficial to have all documentation work the same
> way, and to have stuff like the applications categorization and the
> documentation categorization work as similarly as possible.

Yes, but at least for backwards compatibility it would be nice, if the more 
complex application categorization mechanism wouldn't be mandatory for the 
docs from the beginning on. This would also make life for help browser 
developers easier.

> And even I find myself sometimes wondering something like "Where the
> hell is the documentation for Foo located in the categorization?"  If
> the structure mimicked the applications menu, then documents would be
> easier to find.  Obviously, the categorization has to have more than
> just the applications, because there is documentation that doesn't
> belong to any application.

But it would definitely be nice if at least for the documentation which 
belongs to the apps contained in the menu the doc would reflect that. For 
KHelpCenter this is already the case, by the way ;-)

> All right, I don't really like having the categorization strictly follow
> the heirarchy of files in the filesystem.  I think the Menu spec took a
> huge step forward on that, and we should follow.

In principle yes, but as said before, for backwards compatibility and for 
easier implementation of help browsers I would like to keep that optional for 
the beginning and allow for specifying doc hierarchy by file system 

> As for using .desktop files for the metadata, I have a few reservations,
> but I'm not entirely opposed.  One problem I have is that the syntax
> isn't, to my knowledge, well-defined.  At least I don't know of a real
> specification on them.

Well, there is the specification at If this isn't 
sufficient we should fix that.

> With XML, I have a clearly-defined syntax, and I have a fully conformant
> parser available to me.  In fact, one of the main reasons I concocted my
> own XML format, rather than using actual RDF/XML, is that if I were to
> use RDF/XML, I would feel compelled to support it fully, not some half
> ass subset.  And I don't have an RDF library readily available.

We have parsers for the desktop files as well. In KDE there is a class 
KDesktopFile. I assume there is someting similar in GNOME, isn't it?

> This problem clearly isn't insurmountable, as we do use the .desktop
> format all over the place already.  I've just had my share of experience
> with documentation systems which weren't clearly defined in some manner,
> and people took advantage of things that "happened to work".  This can
> become a real pain in the ass.

Yes, so we should try to address this problem in whatever specification we 
will come up with.

> Another problem I have with .desktop files is that it's not clear to me
> how to do any nesting.  What I outlined allowed a single metadata file
> to reference many different "copies" of the same document.  This sort of
> information can be immensely useful.  It may not be immediately relevant
> to a simple help viewer, but the worst mistake you can make when making
> this sort of thing is that the only thing using your system will be the
> help viewer.

For what cases would you need the concept of copies? For translations of 
documents this is handled by KHelpCenter by having the same desktop file with 
multiple extensions.

> So I have other motives here.  Every now and then, when I get a bit
> tired of putting bugs into Yelp, I take a little time off hacking to
> make empty promises to people.  And one of the things I promise is an
> automatic documentation for the web building tool.  And I mean fully
> automatic.  The *model* presented by the format works very well this.

I don't quite follow you here. What documentation for which web building tool 
do you mean?

> > 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.
> That would be good.  Since you're actually using these sorts of files
> already, you'd have a better idea of what can be done with them.  The
> .desktop files are easier to hand-edit, and developers will be more
> familiar with them, so there is definately an advantage to using them.
> If I can be convinced that they won't cripple the ability to store
> meaningful information, I won't really have any objections.

I have attached the current documentation of the meta data KHelpCenter 
currently uses.

Cornelius Schumacher <schumacher at>
-------------- next part --------------
KHelpCenter documentation meta data structure

KHelpCenter uses meta data files which describe the documentation available in
the system. Each document is represented by a meta data file and shown as an
entry in the KHelpCenter navigation tree view. The meta data contains
information about title and short description of the document, the location of
the document and some more information like how to search the document and
translations of title and description. Document hierarchy is represented as
hierarchy of the meta data files. Directories are also described by a meta data
file which contains the same information as a document meta data file.

Format of the meta data files

The meta files adhere to the Desktop Entry Standard
( Documentation
specific extensions are covered by an own namespace using the prefix "X-DOC-".
The following table describes all keys which are currently used by

Key                         Value     Description

Name                        string    Title of document
Name[xx]                    string    Translated title for language xx
Comment                     string    Short description of document
Comment[xx]                 string    Translated short description for
                                      Language xx
Icon                        string    Name of icon for document
DocPath                     URI       Location of document. In addition to the
                                      standard URI schemes like http: and file:
                                      all schemes which are supported through
                                      kioslaves can be used. In particular the
                                      followind non-standard URI schemes are
                                      help:  KDE manual identified by app name
                                      ghelp: GNOME manual identified by app name
                                      man:   man page
                                      info:  info page
                                      cgi:   output of CGI script
DocPath[xx]                 URI       Language specific location for
                                      language xx
Lang                        langcode  Language of document
X-DOC-Identifier            string    Unique identifier for document, if this
                                      entry is not present the base name of the
                                      file is used as identifier
X-DOC-Indexer               command   Command used for creating a search index
                                      for the document.
                                      The following symbols are replaced by the
                                      corresponding values:
                                      %f - Filename
X-DOC-IndexTestFile         filename  Name of file whose existence indicates
                                      the existence of a usable search index
X-DOC-Search                command   Command used for searching, the output
                                      of the command should be HTML which is
                                      shown in KHelpCenter.
                                      The following symbols in the command are
                                      replaced by the corresponding values:
                                      %k - Words to be searched for
                                      %n - Maximum number of results
                                      %m - Method for combining search words,
                                           can be 'and' or 'or'
                                      %l - Language of documents to be searched
                                      %s - Scope of search. This is a list of
                                           identifiers as given by the
                                           X-DOC-Identifier entry or the bas
                                           name of the desktop file if not
X-DOC-SearchMethod          string    If this entry is 'htdig' htdig is used to
                                      index and search the document. The
                                      Indexer, IndexTestFile and Search entries
                                      aren't required in this case.
X-DOC-SearchEnabledDefault  bool      If set to 'true' the document is searched
                                      by default, if set to 'false' it is not.
                                      This setting is overrideen by user
                                      selected search scopes.
X-DOC-Weight                int       A number indicating the position of the
                                      document within the list of siblings. A
                                      greater weight indicates that the document
                                      is 'heavier', thus shown below 'lighter'
                                      documents. The default weigth is 0.
X-KDE-KHelpcenter           string    If this entry is set to one of the
                                      following values a set of documents
                                      generated by other means than desktop file
                                      meta info is inserted at the place
                                      specified by the desktop file:
                                      'apps'         manuals of applications
                                                     from the start menu
                                      'scrollkeeper' scrollkeeper docs
                                      'applets'      panel applet docs
                                      'kinfocenter'  kinfocenter docs
                                      'kcontrol'     kcontrol module docs
                                      'konqueror'    konqueror plugin docs
                                      'kioslave'     kioslave docs
                                      'info'         info pages

Meta File Location

A list of directories given by the config entry "MetaInfoDirs" in the "Genral"
group of the help center configuration file "khelpcenterrc" (at
$KDEDIRS/share/config) is scanned for desktop files. They are merged to a common
hierarchy. If the "MetaInfoDirs" entry is empty the directory at
$KDEDIRS/share/apps/khelpcenter/plugins is used.

Document Hierarchy

The hierarchy of the documents shown in the help center is reflected by the
hierachy of the desktop files in the filesystem. Directories can have an
associated desktop file with the name ".directory". It can contain all the
keys described above.

Language handling

In addition to translation of meta information like title and short description
of documents which is contained in the meta file, translations of whole
documents are handled. Each translation of a document has an own desktop file.
The language of the document is indicated by adding the language code as
additional suffix to the the filename of the desktop file. The language suffix
is added before the ".desktop" suffix (Example: '' would be the
file name for the german translation of the apache documentation).

KHelpCenter shows only the documents whose language is contained in the list of
used languages configured for the desktop in the control center. A document
corresponding to a desktop file without language suffix is always shown.

More information about the xdg mailing list