Help System Spec 0.2
schumacher at kde.org
Wed Dec 27 17:57:47 EET 2006
On Saturday 25 November 2006 17:39, Don Scorgie wrote:
> I've put up a new version (0.2) for viewing / download at:
> (docbook xml)
This already looks quite good. It seems we are finally getting somewhere :-).
So despite being late I still wanted to make some comments.
> * Removed .directory files
Arranging documentation meta files in a directory hierarchy is a simple way to
structure documentation. For this to work we need the .directory files, so
that the directories can be given user-visible titles which can be shown in
the help browser.
There are other ways to specify hierarchies like the menu spec, but they are
much more complex, so I think it would be good to leave the .directory files
in the help spec as an easy way to allow a structured view to the
documentation. The help browser still can ignore this information, if it uses
a more advanced way for creating a hierarchical display or only offers a flat
view on the documentation.
> * Added new chunks about how to invoke the help browser (+ examples)
> (Preferably through dbus, with alternative)
I like the idea of providing a D-Bus API. This seems to be a good way to
specify a standard way of calling the help system without the overhead of
going through a command line tool.
One question, though: Is D-Bus able to start the help browser on demand when a
call is made to the API or is it needed that the help browser is already
running (providing it is the help browser implementing the API)?
What about adding a call "open_browser", which would open the help browser
without showing a specific document, but with a generic start page?
The open_browser call could also get a DocIdentifier as optional argument, so
that it could open the browser and show the corresponding document. For some
help browsers this might be identical to open_document, but for browsers
which e.g. show a navigation panel it might make a difference (e.g.
open_document only showing the document but not the navigation panel and
open_browser showing both).
What's the use case for the close_document call? Wouldn't it be up to the user
to close the help window? Maybe it's a lack of my phantasy but I can't
imagine a situation where an application wanted to close a help window
> * Remove the help: URI section. It causes confusion and is inextensible
> (installing a package in /opt with the docpath defined as help:<file>
> would point to the wrong place)
One purpose of the help: URIs is to specify a standard location for
documentation files. While it should be possible to install documentation to
other locations it still would be nice to have a standard location, so that
the location where files are installed is not completely arbitrary. To make a
separate spec for this purpose would probably be overkill, so I think it
would be nice to keep this in the help system spec.
Isn't the extensibility aspect taken care of by using $XDG_DATA_DIRS? When
installing a package to a non-standard location, several paths have to be
adjusted anyway, so that binaries, man pages etc. can be found, so in the
example if the corresponding directory under /opt is included in the
XDG_DATA_DIRS variable the help URI would still work.
The help: URIs also address the problem of translated documentation. With the
help URIs it's sufficient to provide one meta file with one DocPath for all
translated versions of a manual. Without the help: URIs you need to put the
exact path into the metafile which means that you either have to supply a
meta file per translation or to put DocPaths for all languages in the meta
file. Both means adding a lot of at least partly redundant information. This
has several problems, e.g. the increased danger of having inconsistent data
or slow parsing of the meta data.
Finally the help: URI scheme provides a solution for addressing a specific
part of a document by using appropriate anchors. This is needed for example
when a dialog has a help button and pressing on the button has to show up the
section of the manual which is describing the dialog.
So, all in all, I think we still need the help: URIs in the spec.
Some other comments:
I think it's preferable to use the suffix ".desktop" for the meta files
instead of ".document". The meta files are valid .desktop files and adhere to
the desktop entry specification, so it seems to be logical to use the suffix
which is specified there. The help system meta files are more an extended
version of the desktop files than a new file type.
Another reason to use the .desktop suffix is that normal desktop files which
for example are used for creating the start menu could additionally also
contain the information for the help system, so the meta information for
application manuals for the help system could be extracted from the same
files without the need to duplicate any data.
As the DocHeritage entry is only used for backwards compatibility it might be
better to leave it out from the specification. It still could be used e.g. as
X-Scrollkeeper-DocHeritage by help browsers which previously used
In the section about language-specific documentation there is the use of an
environment variable $LANGUAGE mentioned. How exactly is this meant to work?
Wouldn't it be better to leave that out of the specification and leave it to
the help system implementation to determine what languages the user wants to
see? I suppose this setting would end up in a configuration dialog of the
help browser anyway. So using environment variables might be a bit
Cornelius Schumacher <schumacher at kde.org>
More information about the xdg