Help System Spec 0.2

[Cornelius Schumacher]

On Saturday 25 November 2006 17:39, Don Scorgie wrote:
>
> I've put up a new version (0.2) for viewing / download at:
> (html)
> http://www.gnome.org/~dscorgie/help-spec-0-2.html
>
> (docbook xml)
> http://www.gnome.org/~dscorgie/help-spec-0.2.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 
programmatically.

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

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

-- 
Cornelius Schumacher <schumacher at kde.org>