return to index

Overview

Rarian meta-data files are desktop files as defined by the proposed XDG help system spec (a copy of which is distributed with the Rarian source tarball). A copy of specification on which this version of Rarian is based can also be found here.

This section describes how to write the meta-data files and how to ensure they are picked up by the Rarian library.

WARNING: The meta-data format is not currently complete and is liable to change in incompatible ways in future releases. It is strongly recommended to use the scrollkeeper compatibility mode at present.

The basic structure

A sample meta-data file looks like:

Anatomy

The above file introduces most elements of the meta-data file format.

• Comments are marked as lines beginning with a '#' character and are ignored by the parser.
• Section names are encased in square brackets ([ ]) beginning a line. A [document] section is required to be valid.
• Fields are of the form "Name=value"
• Other languages can be included by specifying the language type in square brackets at the end of the name: "Name[lang]=value"
• Key names are case-sensitive. "Name" is not the same as "name".
• Any unknown keys are ignored.
• A section continues until another section or end-of-file is encountered

Recognised Fields

The [document] section of meta-data files can contain a number of fields, some of which are required. This section gives details of what fields are available and what they do. Fields marked as strong are necessary.

Name

The title of the document

DocPath

The path to the file. This should be in the form of a URI as above.

DocType

The mime type of the document.

Comment

Typically, help browsers will give a short description of the document to allow people to determine whether they want to look at the document. This is what is displayed

Icon

The icon associated with the document, if there is one.

Categories

A semi-colon separated list of categories the document is relevant to. The available categories can be found in the XDG menu spec

DocWeight

The "weighting" given to documents. Documents with higher DocWeight are shown below documents with lower DocWeights. This should generally not be used without a good reason

DocIdentifier

The DocIdentifier is a reverse-DNS identifier used to determine whether two documents describe the same subject. The general form of the DocIdentifier is "org.<organisation>.<subject>". The "org." should be substituted for "com." for commercial programs. Please choose the <organisation> appropriately.

DocLang

When the meta-data file describes a single language, but not the "C" locale, this field gives the language. This is used for (e.g.) distributing language packs.

TODO: Describe children element and where they are useful

Additional Fields

There are several fields that should not be used except in specific circumstances. These are described here.

x-DocHeritage

This is used when moving from scrollkeeper. The scrollkeeper translation utilities form a new-style identifier of the form "org.scrollkeeper.<scrollkeeper-seriesid>". In order to ensure your new document is picked up in it's place, you must specify this field in the form of:

x-DocHeritage=org.scrollkeeper.<seriesid>

x-Scrollkeeper-omf-loc

This should never be used. It is used by the scrollkeeper compatibility to provide the location of the scrollkeeper omf files.

Making your meta-data files accessible

By default, Rarian will pick up meta-data files found in the "help" subdirectory of the XDG_DATA_DIRS environment variable. If this environment variable is not set, Rarian will default to checking in /usr/share/help and /usr/local/share/help.

In addition, the environment variable XDG_DATA_HOME can also be used to provide user-specific files. Rarian will check $XDG_DATA_HOME/.share/help. If XDG_DATA_HOME is not set, it defaults to $HOME.

To be picked up by Rarian, the meta-data file must be placed in one of these directories (or a sub-directory thereof). The only other requisite for documents is that the meta-data file must have the suffix ".document". For example, the example file presented above would be named "beanstalk.document".

Accessing your documentation

Note: This section is due for heavy revision once several things come together. It is aimed at GNOME documentation currently. Once the XDG help spec is implemented / supported, this will become obsolete

Having written your documentation, copied your meta-data file to the correct location, you now have several options to access your documentation from your application:

• Use libgnome-provided help functions.
• Call "yelp" from the command line, with the parameter "ghelp:>name of meta-data file<". I.e. to load the beanstalk document, the command line would be: "yelp ghelp:beanstalk".

Note: libgnome currently uses a different method for determining the location and name of a file to be opened within yelp. This may require some playing around with. We are actively working to make this obsolete and rely more on the DocIdentifier.