Shared Help System, Take N (for N >= 3)

[Shaun McCance]

Hi folks,

A few weeks ago, documentation people from GNOME, KDE, XFCE,
Ubuntu, and Fedora met up in Chicago. We discussed various
documentation-related topics, trying to get on the same page
and start a little more cross-team collaboration.

One of the things we discussed was a common location and URI
scheme for installed help documents. I'll outline the basic
proposal below. I'd like feedback from other developers and
from people involved with other projects.

This system deals explicitly with user help, the stuff that
appears when you hit F1. I believe we can handle developer
documentation using either this system or something similar,
but right now, my focus is user help.

Help documents are installed under $XDG_DATA_DIRS/help. This
has language subdirectories. So, for example, a Brazilian user
might have the following:

  /usr/share/help/C
  /usr/share/help/pt
  /usr/share/help/pt_BR

There are subdirectories for each document under the language
directories. So for the beanstalk-help document, you'd have:

  /usr/share/help/C/beanstalk-help
  /usr/share/help/pt/beanstalk-help
  /usr/share/help/pt_BR/beanstalk-help

These document directories then contain the actual files for
the documentation. They may have subdirectories for resources
like images or XIncluded files, but the core documentation
files are expected to be directly in the document directory.

We do not mandate what format the documentation has to be in.
Implementations that don't understand what's there will simply
not be able to display that document. You can, however, install
your document in multiple formats. Implementations can choose
whichever format they like best.

We do recommend best practices for HTML, DocBook, and Mallard.
HTML documents are expected to have an index.html file. Mallard
documents are expected to have an index.page file. And DocBook
documents are expected to be named index.docbook.

The URI scheme has the following form:

  help:document/page?options#anchor

Note that there is no leading slash. KDE currently uses help:
URIs with a leading slash, effectively as a rerooted filesystem
on the language subdirectories. Implementations do not have to
support this.

The page, options, and anchor are all optional. Implementations
search for a document under the language subdirectories of the
user's preferred languages. Directories that are higher in
$XDG_DATA_DIRS take precedence over languages.

  for dir in $XDG_DATA_DIRS:
    for lang in get_language_names():
      # Check for index.page, index.html, or index.docbook in
      # $dir/$lang/$document/

The page argument specifies a discrete chunk to display. For
Mallard documents, this maps to a page ID. For HTML, this maps
to a base file name, without the .html extension. For DocBook,
this maps to an ID within the file. Note that implementations
might chunk DocBook documents differently. If page refers to
an element that doesn't get chunked, an implementation should
show the enclosing chunk. Unless there's an anchor argument,
they should scroll to the relevant portion.

The anchor argument specifies an id to scroll to within the
page. The options argument is expected to be formatted like
a query string, but we don't currently recommend any keys.
It can be used for things like overriding the language or
specifying keys for conditional processing.

All relative path references in documentation (src="foo.png")
are looked up relative to the entire path.

This does not provide a mechanism for installing metadata
files. I'm not really interested in doing that anymore, and
nobody else seemed to want it either. I can go into reasons
why I don't think it matters if anybody wants to hear it.

I'd love to get some feedback on this.

Thanks,

Shaun McCance
http://syllogist.net/