[kde-doc-english] Shared Help System

[Shaun McCance]

Hi folks,

This is a rough write-up of what Rich and I discussed about
a shared help system at the Desktop Help Summit about a week
ago. I'm sending it first to the GNOME and KDE documentation
lists. I'll send this out to more teams after we've all had
a chance to comment.

Currently, GNOME installs documents to $DATADIR/gnome/help,
using the document name and then the language, like so:

  /usr/share/gnome/help/mydocument/C/

GNOME references documents using the ghelp: URI scheme, which
in its most basic form looks like this:

  ghelp:mydocumnt?somepage

This scheme has been extended and tortured inside Yelp in mostly
backwards-compatible but completely undocumented ways over the
years.

KDE documents *somewhere*, where that somewhere seems to vary
from distro to distro. It uses the language first, then the
document name, like this:

  /usr/share/doc/kde4/html/C/mydocument

It references documents using the help: URI scheme. This is
effectively a rerooting on a path, and always starts with a
slash, like this:

  help:/mydocument

Because it's a rerooting, you can do arbitrary file lookups
with it. So something like this works:

  help:/common/foo/bar.js

This would point to:

  usr/share/doc/kde4/html/C/common/foo/bar.js

(Rich, correct me if I'm wrong please.)

KDE and GNOME both also have metadata files. I'm ignoring
what they do with them, because this proposal doesn't use
them.

The proposal is to put everything in $DATADIR/help (where
$DATADIR should be looked up according to the XDG basedir
spec), with language name first, then document name. So:

  /usr/share/help/C/mydocument/

The standard way to reference a document would be with
the help: URI scheme without a leading slash. KDE can
continue to use the slash form internally. The basic
form of the URI scheme is this:

  help:document[/page][?options][#anchor]

Things in brackets are optional. The document argument
specifies the documentation directory to read from. That
directory could contain help in any of a number of formats.
The page argument specifies a particular page to show. The
options is formatted as a query string and can be used for
things like language overrides or conditional processing.
Finally, the anchor argument specifies an anchor to scroll
to within a page.

To remain flexible, we don't mandate the formats that can
be installed. But for any format, the information in the
URI must be mapped to something meaningful.

That said, we do provide recommendations for dealing with
three types of installed help: DocBook, Mallard, and HTML.

For DocBook documents, the directory is expected to contain
either an index.docbook or a docname.xml file, where docname
is the name of the documentation directory (help:docname).
The page argument specifies a section or other element in
the DocBook to be shown. Help viewers might chunk in a way
that causes page not to reference a top-level page element.
If that happens, the help viewer should just display the
enclosing page.

For Mallard documents, the directory is expected to contain
.page files. Mallard mandates an index.page file, so you
can just check for that file. The page argument specifies
a page ID (not a file name).

For HTML documents, the directory is expected to contain
.html files. The page argument specifies the base file
name, without the .html extension.

Note that KDE currently installs a DocBook file along with
pre-generated HTML packed into a bzip2-compressed archive.
This proposal doesn't deal with that. KDE can continue to
use its pre-generated file, as long as its DocBook file is
there for general compatibility.

Please give feedback.

Thanks,
Shaun