return to index

# Rarian Scrollkeeper Compatibility

In addition to its new (and better) meta-data format, Rarian also provides backwards compatibility for scrollkeeper. This section outlines the basics of scrollkeeper files and how to use them. Don't expect too much though.

Note: If you are using GNOME, it is strongly recommended that you use gnome-doc-utils, which is described on live.gnome.org.

## Scrollkeeper Meta-data files

Scrollkeeper uses omf files, which are XML based. The main text elements that are of interest are:

title
  The title of the document
description
  The description of the document (the blurb that appears in table of contents)
creator
  The creator of the documentation
maintainer
  The person that currently looks after the documentation
type
  The type of the documentation ("user's guide" etc.)
date
  The last revision date of the documentation

Other fields that have attributes:

node
  attributes: what is does
version
  identifier: Who knows?, date: As the date field
subject
  category: Which category the document belongs to. A list of categories can be found on the scrollkeeper website
format
  mime: the mime type of the document, dtd: the dtd of the document (like "-//OASIS//DTD DocBook XML V4.3//EN")
identifier
  url: The URI of the actual documentation (bet you were wondering where that was, weren't you?)
language
  code: The language code describing the language the document described by the meta-data is in..
relation
  seriesid: The unique scrollkeeper seriesid. Can be generated using the scrollkeeper-gen-seriesid program.
rights
  type: The license the documentation is available under, license.version: The specific version of the license, holder: Who actually holds the license.

## Example scrollkeeper file

    <?xml version="1.0" encoding="utf-8"?>
    <omf>
      <resource>
        <creator>The Professor <theprof@example.com></creator>
        <maintainer>The Professor <theprof@example.com></maintainer>
        <title>The Beanstalk User Guide</title>
        <date>June 2021</date>
        <version identifier="The Beanstalk User Guide v1.0" date="June 2021"/>
        <subject category="GNOME|Desktop"/>
        <description>
          Beanstalks are big and may, if you're very, very lucky, lead to
          golden eggs.
        </description>
        <type>user's guide</type>
        <format mime="application/xhtml+xml" dtd="-//W3C//DTD XHTML 1.0 Strict//EN"/>
        <identifier url="beanstalk.xhtml"/>
        <language code="C"/>
        <relation seriesid="ceae33be-2a60-11dc-9e02-e1e3ec1cb44f"/>
        <rights type="GNU FDL" license.version="1.1" holder="The Professor"/>
      </resource>
    </omf>

Basically, it's easier to copy this example and modify it to suit your needs than to try and write your own.

Normally, the name of your omf files (after installation) should be <package name>-<langcode>.omf. Before installation, you can name it whatever you want. However, I'd recommend:

    <package name>-<langcode>.omf.in

So for the beanstalk example, the distributed file (in source archives, i.e. to allow people to install it anywhere) would be:

    beanstalk-C.omf.in

Which is then converted using scrollkeeper-preinstall, described below.

## Installing documentation

Scrollkeeper installation is a little ... quirky. First, copy your actual documentation to where you want. To install the meta-data, fist run scrollkeeper-preinstall using the arguments like:

    scrollkeeper-preinstall <installed doc name> <current omf name> <new omf name>

For example, for the beanstalk manual, this might look like:

    scrollkeeper-preinstall /usr/share/beanstalk/manual/C/beanstalk.xhtml beanstalk-pre-C.omf beanstalk-C.omf

After that, you can now copy the newly generated omf file into <prefix>/share/omf/<name>/ where <name> is generally the name of your package. Repeat this procedure for each language.

Afterward, you can now run scrollkeeper-update. This has a few options you must specify to get the correct behaviour. This will need some tweaking, but in general:

    scrollkeeper-update -o <prefix>/share/omf

Should get you reasonably close. (If using Rarian, this will be sufficient).

And that's it. You'll probably want to put this stuff in your makefiles. I have no idea how to do all this. I'd recommend looking for other packages that use scrollkeeper and adapt their stuff. (It's like the old autoconf joke - only 2 people have ever written a configure.in, everyone else just copies them)