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

[Stefan.Kost at nokia.com]

Hi,

>-----Original Message-----
>From: xdg-bounces at lists.freedesktop.org [mailto:xdg-
>bounces at lists.freedesktop.org] On Behalf Of ext Shaun McCance
>Sent: 16 April, 2010 18:24
>To: xdg at lists.freedesktop.org
>Subject: Shared Help System, Take N (for N >= 3)
>
>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.

I think Mallard documents should have a index.mallard file to be consistent.

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

So there won't be a structured index of document anymore. Or are you taking categories from the desktopfile (assuming that there is a beanstalk.desktop)?

Besides the two small comment, looks good.

Stefan

>
>I'd love to get some feedback on this.
>
>Thanks,
>
>Shaun McCance
>http://syllogist.net/
>
>
>
>_______________________________________________
>xdg mailing list
>xdg at lists.freedesktop.org
>http://lists.freedesktop.org/mailman/listinfo/xdg