return to index

# LibRarian Reference

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.

Note: Rarian is currently API-unstable. You are advised to explicitly check and use exact versions of Rarian

## Including the library

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.

Alternatively, you can set the cflags and libs yourself. The correct include path is ">prefix</include/rarian" and the library name is "rarian".

## Overview of Rarian library makeup

Rarian is currently split into three parts:

- The main documents access functions
- The man page access functions
- The info page access functions

which gives access to the three different forms of documentation available to Rarian. Each of these is discussed in the relevant section here.

## Commonalities

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.

## Main Documents

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.

The following documents can be accessed by including the "rarian.h" file.

### Preamble

Functions returning meta-data do so in a struct, the RrnReg. The definition for this struct looks like:

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

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:

heritage
  The x-DocHeritage field of the meta-data file. Should generally be ignored.
omf_location
  The x-Scrollkeeper-omf-loc field of the meta-data file. Should generally be ignored.
ghelp_name
  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.
children
  When a document consists of sections, this will contain a pointer to the lists of sections. TODO: Add information about sections.

Note: The returned structure must never be freed.

### For each functions

rrn_for_each (RrnForeachFunc funct, void * user_data)

Iterates through each available document in turn and calls funct for each. If funct returns FALSE, iteration is stopped immediately.

void rrn_for_each_in_category (RrnForeachFunc funct, char * category, void *user_data)

Iterates through each document in category and calls funct for each. If funct returns FALSE, iteration is stopped immediately.

The prototype of RrnForeachFunc looks like:

    typedef int (* RrnForeachFunc) (void * reg, void *data);

The void *reg will be a pointer to the RrnReg for the entry as described above. The void *data parameter is the user_data parameter passed into the for-each function.

### Finding functions

RrnReg * rrn_find_entry_from_uri (char *uri)

Finds the relevant entry from the uri. This simply compares the uri to the uri field of the RrnReg and returns the RrnReg if they match. This will find the first match and ignore further matches. If no match is found, NULL is returned.

RrnReg * rrn_find_from_name (char *name)

Finds the relevant entry from the name. This simply compares the name to the name field of the RrnReg and returns the RrnReg if they match. This will find the first match and ignore further matches. If no match is found NULL is returned.

RrnReg * rrn_find_from_ghelp (char *ghelp)

Finds the relevant entry from the ghelp. This simply compares the ghelp to the ghelp_name field of the RrnReg and returns the RrnReg if they match. This will find the first match and ignore further matches. The passed in parameter ghelp must have the "ghelp:" removed from the front of the URI. If no match is found, NULL is returned.

### Misc. functions

Rarian provides several miscellaneous functions in this sections. These are described here.

void rrn_set_language (char *lang_code)

By default, Rarian will set itself up using the $LANGUAGE environment variable. You can override this behaviour by calling this function with lang_code 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.

void rrn_shutdown ()

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.

## Man pages

### Preamble

Rarian provides access to installed man pages on the system. This functionality can be accessed by including the "rarian-man.h" file.

As with the main documents, functions return structs containing meta-data, the RrnManEntry struct, as described below:

      typedef struct _RrnManEntry {
        char *name;
        char *path;
        char *section;
        char *comment;
      } RrnManEntry;

Each of these fields are self-explanatory.

### For each functions

void rrn_man_for_each (RrnManForeachFunc funct, void * user_data)

This function iterates through all man pages and calls funct for each one. If funct returns FALSE, iteration is stopped immediately.

void rrn_man_for_each_in_category (char *category, RrnManForeachFunc funct, void * user_data)

Iterates through each man page within category and calls funct for each one. If funct returns FALSE, iteration is stopped immediately. Category names can be found by calling rrn_man_get_categories, described below.

The prototype for the RrnManForeachFunc is:

typedef int (* RrnManForeachFunc) (void * reg, void *data)

where reg is a pointer to the RrnManEntry and data is the user_data passed in to the for-each function.

### Find functions

RrnManEntry *rrn_man_find_name (char *name, char *sect)

Locates the man page entry with the name name and returns the relevant RrnManEntry. If sect is non-NULL, only entries in sect will be considered. If no entry is found, NULL is returned.

### Misc. Functions

char **rrn_man_get_categories (void)

Returns an a list of char *s which describe the categories available in Rarian. The final entry in the list is NULL

void rrn_man_shutdown ()

Shuts down and frees all memory used by the man page section of Rarian.

## Info Pages

### Preamble

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 RrnInfoEntry struct, which is declared as:

      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;

The elements are described as:

name
  The base name of the actual file. This should generally not be used.
shortcut_name
  Currently unused
base_filename
  The filename of the initial document. This should be the file to parse.
base_path
  The path where the document lives.
section
  The section of the document the entry points to (like an anchor in html documents)
doc_name
  The "title" of the entry. This should be used for table of content generation.
compression
  Described below.
category
  The category the document belongs in. A list of categories can be found using rrn_info_get_categories, described below.

#### Compression

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)

     typedef enum _RrnInfoCompression {
        INFO_ENCODING_NONE = 0,
        INFO_ENCODING_GZIP,
        INFO_ENCODING_BZIP,
        INFO_ENCODING_LZMA,
        INFO_ENCODING_UNKNOWN,
      } RrnInfoCompression;

### For each functions

void rrn_info_for_each (RrnInfoForeachFunc funct, void * user_data)

Iterates over all info documents available and calls funct for each one. If func returns FALSE, iteration is stopped immediately.

void rrn_info_for_each_in_category (char *category, RrnInfoForeachFunc funct, void * user_data)

Iterates over all info documents available in the category category and calls funct for each one. If func returns FALSE, iteration is stopped immediately. A list of available categories can be found using rrn_info_get_categories described below.

The prototype for RrnInfoForeachFunc looks like:

typedef int (* RrnInfoForeachFunc) (void * reg, void *data)

where reg is the RrnInfoEntry associated with the document and data is the user_data element passed into the for-each function.

### Finding functions

RrnInfoEntry *rrn_info_find_from_uri (char *uri, char *section)

Iterates through each entry in section and searches for the document matching uri. If section is NULL, all sections are searched. If no match is found, NULL is returned.

### Misc. Functions

char **rrn_info_get_categories (void)

Returns a list of available categories. The list is NULL-terminated and must not be freed.

void rrn_info_shutdown ()

Shuts down and frees all memory used by Rarian info stuff.