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