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
