| Server IP : 134.236.49.22 / Your IP : 216.73.216.114 Web Server : Apache/2.2.15 (Fedora) System : Linux km10.dyndns.org 2.6.31.5-127.fc12.i686.PAE #1 SMP Sat Nov 7 21:25:57 EST 2009 i686 User : apache ( 48) PHP Version : 5.3.3 Disable Function : NONE MySQL : ON | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/librarian/manual/ |
Upload File : |
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Writing Rarian Meta-data files</title> </head> <body> <p><a href="index.xhtml">return to index</a></p> <h2>Overview</h2> <p>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 <a href="http://www.gnome.org/~dscorgie/help-spec-0-2.html">here</a>.</p> <p>This section describes how to write the meta-data files and how to ensure they are picked up by the Rarian library.</p> <p><strong>WARNING</strong>: 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 <a href="rar-skcompat.xhtml">scrollkeeper compatibility mode</a> at present.</p> <hr/> <h2>The basic structure</h2> <p>A sample meta-data file looks like:</p> <quote> <p># An example meta-data scroll file - beanstalk.document</p> <p>[document]</p> <p>Name=The Beanstalk Manual</p> <p>Name[de]=Das Beanstalk Manual</p> <p>DocIdentifier=org.freedesktop.beanstalk</p> <p>Categories=Utility;Finance</p> <p>DocPath=file:///usr/share/fdo/help/beanstalk/C/beanstalk.html</p> <p>DocPath[de]=file:///usr/share/fdo/help/beanstalk/de/beanstalk.html</p> <p>DocType=application/xhtml+xml</p> <p>Comment=Beanstalk provides access to golden eggs. Climb it and find your destiny</p> <p>Comment[de]=German language not known. Sorry.</p> </quote> <h3>Anatomy</h3> <p>The above file introduces most elements of the meta-data file format.</p> <ul> <li>Comments are marked as lines beginning with a '#' character and are ignored by the parser.</li> <li>Section names are encased in square brackets ([ ]) beginning a line. A [document] section is required to be valid.</li> <li>Fields are of the form "Name=value"</li> <li>Other languages can be included by specifying the language type in square brackets at the end of the name: "Name[lang]=value"</li> <li>Key names are case-sensitive. "Name" is not the same as "name".</li> <li>Any unknown keys are ignored.</li> <li>A section continues until another section or end-of-file is encountered</li> </ul> <h3>Recognised Fields</h3> <p>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>strong</strong> are necessary.</p> <dl> <dt><strong>Name</strong></dt> <dd>The title of the document</dd> <dt><strong>DocPath</strong></dt> <dd>The path to the file. This should be in the form of a URI as above.</dd> <dt><strong>DocType</strong></dt> <dd>The mime type of the document.</dd> <dt>Comment</dt> <dd>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</dd> <dt>Icon</dt> <dd>The icon associated with the document, if there is one.</dd> <dt><strong>Categories</strong></dt> <dd>A semi-colon separated list of categories the document is relevant to. The available categories can be found in the <a href="http://standards.freedesktop.org/menu-spec/latest/apa.html">XDG menu spec</a></dd> <dt>DocWeight</dt> <dd>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</dd> <dt><strong>DocIdentifier</strong></dt> <dd>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.</dd> <dt>DocLang</dt> <dd>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.</dd> </dl> <p><strong>TODO</strong>: Describe children element and where they are useful</p> <h3>Additional Fields</h3> <p>There are several fields that should not be used except in specific circumstances. These are described here.</p> <dl> <dt>x-DocHeritage</dt> <dd>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: <p>x-DocHeritage=org.scrollkeeper.<seriesid></p> </dd> <dt>x-Scrollkeeper-omf-loc</dt> <dd>This should never be used. It is used by the scrollkeeper compatibility to provide the location of the scrollkeeper omf files.</dd> </dl> <h2>Making your meta-data files accessible</h2> <p>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.</p> <p>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.</p> <p>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".</p> <h3>Accessing your documentation</h3> <p><strong>Note:</strong> 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</p> <p>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:</p> <ul> <li>Use libgnome-provided help functions.</li> <li>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".</li> </ul> <p><strong>Note:</strong> 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.</p> </body> </html>