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)