/usr/share/librarian/manual/rar-mdf.xhtml is in librarian-dev 0.8.1-6.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 | <?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>
|