Hi, >-----Original Message----- >From: [email protected] [mailto:xdg- >[email protected]] On Behalf Of ext Shaun McCance >Sent: 16 April, 2010 18:24 >To: [email protected] >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 >[email protected] >http://lists.freedesktop.org/mailman/listinfo/xdg _______________________________________________ xdg mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/xdg
