/usr/share/librarian/manual/rar-lib.xhtml is in librarian-dev 0.8.1-6+b1.
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 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 | <?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>LibRarian Reference</title>
</head>
<body>
<p><a href="index.xhtml">return to index</a></p>
<h1>LibRarian Reference</h1>
<p>This section gives an overview of the Rarian Library. It outlines
how to harness the power of Rarian and gives an overview of the
available functions.</p>
<p><strong>Note</strong>: Rarian is currently API-unstable. You are
advised to explicitly check and use exact versions of Rarian</p>
<h2>Including the library</h2>
<p>You can include the library in your application by using
pkg-config to set the correct include and lib flags. The name to
check for is "rarian". You should check for exact versions at this
stage as Rarian API is liable to change in future releases.</p>
<p>Alternatively, you can set the cflags and libs yourself. The
correct include path is ">prefix</include/rarian" and the
library name is "rarian".</p>
<h2>Overview of Rarian library makeup</h2>
<p>Rarian is currently split into three parts:</p>
<ul>
<li>The main documents access functions</li>
<li>The man page access functions</li>
<li>The info page access functions</li>
</ul>
<p>which gives access to the three different forms of documentation
available to Rarian. Each of these is discussed in the relevant
section here.</p>
<h2>Commonalities</h2>
<p>Each of the three "sections" of LibRarian share commonalities. The
primary one is initialisation. In all three cases, initialisation
happens implicitly on the first call requiring access to the internal
list of documents. This means the documents should always be
available when calling into the functions.</p>
<h2>Main Documents</h2>
<p>Main documents are defined by anything with an equivalent "scroll"
file. This documentation can be of any form and Rarian can provide
lists of the documentation. The scroll files are picked up from
$XDG_DATA_DIRS/help and form the basis for most of Rarian.</p>
<p>The following documents can be accessed by including the
"rarian.h" file.</p>
<h3>Preamble</h3>
<p>Functions returning meta-data do so in a struct, the RrnReg. The
definition for this struct looks like:</p>
<pre>
struct _RrnReg
{
char *name;
char *uri;
char *comment;
char *identifier;
char *type;
char *icon;
char **categories;
int weight;
char *heritage;
char *omf_location;
char *ghelp_name;
char *lang;
RrnSect *children;
};
</pre>
<p>Most of these fields are self-explanatory and match up with the
fields in the scroll files. The ones that do not are described
below:</p>
<dl>
<dt>heritage</dt>
<dd>The x-DocHeritage field of the meta-data file. Should generally
be ignored.</dd>
<dt>omf_location</dt>
<dd>The x-Scrollkeeper-omf-loc field of the meta-data file. Should
generally be ignored.</dd>
<dt>ghelp_name</dt>
<dd>The abbreviated name of the meta-data file. Using the beanstalk
example, this field would be filled with "beanstalk". When a user
requests a "ghelp" uri, this field should be compared to the requested
URI (sans the ghelp prefix). Otherwise, this field should be ignored.</dd>
<dt>children</dt>
<dd>When a document consists of sections, this will contain a pointer
to the lists of sections. <strong>TODO:</strong> Add information
about sections.</dd>
</dl>
<p><strong>Note</strong>: The returned structure must never be freed.</p>
<h3>For each functions</h3>
<p><strong>rrn_for_each (RrnForeachFunc funct, void *
user_data)</strong></p>
<p>Iterates through each available document in turn and calls
<em>funct</em> for each. If <em>funct</em> returns <em>FALSE</em>,
iteration is stopped immediately.</p>
<p><strong>void rrn_for_each_in_category (RrnForeachFunc funct, char * category,
void *user_data)</strong></p>
<p>Iterates through each document in <em>category</em> and calls
<em>funct</em> for each. If <em>funct</em> returns <em>FALSE</em>,
iteration is stopped immediately.</p>
<p>The prototype of RrnForeachFunc looks like:</p>
<pre>typedef int (* RrnForeachFunc) (void * reg, void *data);</pre>
<p>The <em>void *reg</em> will be a pointer to the RrnReg for the
entry as described above. The <em>void *data</em> parameter is the
<em> user_data</em> parameter passed into the for-each function.</p>
<h3>Finding functions</h3>
<p><strong>RrnReg * rrn_find_entry_from_uri (char *uri)</strong></p>
<p>Finds the relevant entry from the <em>uri</em>. This simply
compares the <em>uri</em> to the <em>uri</em> field of the RrnReg and
returns the <em>RrnReg</em> if they match. This will find the first
match and ignore further matches. If no match is found, <em>NULL</em> is returned.</p>
<p><strong>RrnReg * rrn_find_from_name (char *name)</strong></p>
<p>Finds the relevant entry from the <em>name</em>. This simply
compares the <em>name</em> to the <em>name</em> field of the RrnReg and
returns the <em>RrnReg</em> if they match. This will find the first
match and ignore further matches. If no match is found <em>NULL</em>
is returned.</p>
<p><strong>RrnReg * rrn_find_from_ghelp (char *ghelp)</strong></p>
<p>Finds the relevant entry from the <em>ghelp</em>. This simply
compares the <em>ghelp</em> to the <em>ghelp_name</em> field of the RrnReg and
returns the <em>RrnReg</em> if they match. This will find the first
match and ignore further matches. The passed in parameter
<em>ghelp</em> must have the "ghelp:" removed from the front of the
URI. If no match is found, <em>NULL</em> is returned.</p>
<h3>Misc. functions</h3>
<p>Rarian provides several miscellaneous functions in this sections.
These are described here.</p>
<p><strong>void rrn_set_language (char *lang_code)</strong></p>
<p>By default, Rarian will set itself up using the $LANGUAGE
environment variable. You can override this behaviour by calling this
function with <em>lang_code</em> set to the desired language.
Multiple language codes can be specified using colon-delimiting. When
called, this function will re-initialise the internal list of
documents to the desired language.</p>
<p><strong>void rrn_shutdown ()</strong></p>
<p>This function shuts down Rarian, freeing any used memory. This is
generally not needed, though may be useful for low-memory situations
when it is known that Rarian will not be necessary again.</p>
<h2>Man pages</h2>
<h3>Preamble</h3>
<p>Rarian provides access to installed man pages on the system. This
functionality can be accessed by including the "rarian-man.h"
file.</p>
<p>As with the main documents, functions return structs containing
meta-data, the <em>RrnManEntry</em> struct, as described below:</p>
<pre>
typedef struct _RrnManEntry {
char *name;
char *path;
char *section;
char *comment;
} RrnManEntry;
</pre>
<p>Each of these fields are self-explanatory.</p>
<h3>For each functions</h3>
<p><strong>void rrn_man_for_each (RrnManForeachFunc funct, void *
user_data)</strong></p>
<p>This function iterates through all man pages and calls
<em>funct</em> for each one. If <em>funct</em> returns FALSE,
iteration is stopped immediately.</p>
<p><strong>void rrn_man_for_each_in_category (char *category,
RrnManForeachFunc funct, void * user_data)</strong></p>
<p>Iterates through each man page within <em>category</em> and calls
<em>funct</em> for each one. If <em>funct</em> returns FALSE,
iteration is stopped immediately. Category names can be found by
calling <em>rrn_man_get_categories</em>, described below.</p>
<p>The prototype for the RrnManForeachFunc is:</p>
<p><strong>typedef int (* RrnManForeachFunc) (void * reg, void
*data)</strong></p>
<p>where <em>reg</em> is a pointer to the <em>RrnManEntry</em> and
<em>data</em> is the <em>user_data</em> passed in to the for-each
function.</p>
<h3>Find functions</h3>
<p><strong>RrnManEntry *rrn_man_find_name (char *name, char
*sect)</strong></p>
<p>Locates the man page entry with the name <em>name</em> and returns
the relevant <em>RrnManEntry</em>. If <em>sect</em> is non-NULL, only
entries in <em>sect</em> will be considered. If no entry is found,
<em>NULL</em> is returned.</p>
<h3>Misc. Functions</h3>
<p><strong>char **rrn_man_get_categories (void)</strong></p>
<p>Returns an a list of <em>char *</em>s which describe the categories
available in Rarian. The final entry in the list is <em>NULL</em></p>
<p><strong>void rrn_man_shutdown ()</strong></p>
<p>Shuts down and frees all memory used by the man page section of
Rarian.</p>
<h2>Info Pages</h2>
<h3>Preamble</h3>
<p>Rarian provides access to info pages available on the system by
parsing the info "dir" file to gather the available documents. All
functions to handle info meta-data can be accessed by including the
"rarian-info.h" file. Functions returning meta-data return a <em>RrnInfoEntry</em> struct,
which is declared as:</p>
<pre>
typedef struct _RrnInfoEntry {
char *name;
char *shortcut_name;
char *base_filename;
char *base_path;
char *section;
char *doc_name;
char *comment;
RrnInfoCompression compression;
char *category;
} RrnInfoEntry;
</pre>
<p>The elements are described as:</p>
<dl>
<dt>name</dt>
<dd>The base name of the actual file. This should generally not be used.</dd>
<dt>shortcut_name</dt>
<dd>Currently unused</dd>
<dt>base_filename</dt>
<dd>The filename of the initial document. This should be the file to parse.</dd>
<dt>base_path</dt>
<dd>The path where the document lives.</dd>
<dt>section</dt>
<dd>The section of the document the entry points to (like an anchor in
html documents)</dd>
<dt>doc_name</dt>
<dd>The "title" of the entry. This should be used for table of
content generation.</dd>
<dt>compression</dt>
<dd>Described below.</dd>
<dt>category</dt>
<dd>The category the document belongs in. A list of categories can be
found using rrn_info_get_categories, described below.</dd>
</dl>
<h4>Compression</h4>
<p>Rarian provides a guess at the compression used for the info
files in the "compression" field of the RrnInfoEntry struct. This can
be one of the following enum (defined in rarian-info.h)</p>
<pre>
typedef enum _RrnInfoCompression {
INFO_ENCODING_NONE = 0,
INFO_ENCODING_GZIP,
INFO_ENCODING_BZIP,
INFO_ENCODING_LZMA,
INFO_ENCODING_UNKNOWN,
} RrnInfoCompression;
</pre>
<h3>For each functions</h3>
<p><strong>void rrn_info_for_each (RrnInfoForeachFunc funct, void *
user_data)</strong></p>
<p>Iterates over all info documents available and calls <em>funct</em>
for each one. If <em>func</em> returns <em>FALSE</em>, iteration is
stopped immediately.</p>
<p><strong>void rrn_info_for_each_in_category (char *category, RrnInfoForeachFunc funct, void * user_data)</strong></p>
<p>Iterates over all info documents available in the category
<em>category</em> and calls <em>funct</em>
for each one. If <em>func</em> returns <em>FALSE</em>, iteration is
stopped immediately. A list of available categories can be found
using rrn_info_get_categories described below.</p>
<p>The prototype for <em>RrnInfoForeachFunc</em> looks like:</p>
<p><strong>typedef int (* RrnInfoForeachFunc) (void * reg, void
*data)</strong></p>
<p>where <em>reg</em> is the <em>RrnInfoEntry</em> associated with the
document and <em>data</em> is the <em>user_data</em> element passed
into the for-each function.</p>
<h3>Finding functions</h3>
<p><strong>RrnInfoEntry *rrn_info_find_from_uri (char *uri, char
*section)</strong></p>
<p>Iterates through each entry in <em>section</em> and searches for
the document matching <em>uri</em>. If <em>section</em> is
<em>NULL</em>, all sections are searched. If no match is found,
<em>NULL</em> is returned.</p>
<h3>Misc. Functions</h3>
<p><strong>char **rrn_info_get_categories (void)</strong></p>
<p>Returns a list of available categories. The list is
NULL-terminated and must not be freed.</p>
<p><strong>void rrn_info_shutdown ()</strong></p>
<p>Shuts down and frees all memory used by Rarian info stuff.</p>
</body>
</html>
|