ScrollKeeper makes a couple small extensions to the standard OMF in order to gain some useful benefits for help and documentation browsers. This section describes these extensions and what they are used for. All OMF files which are intended to be used by ScrollKeeper should include these extensions.
ScrollKeeper has added another attribute, "seriesid", to OMF element 14, "relation". The seriesid is used to specify a group (or series) of documents which are related. For example, multiple versions, formats, and translations of a single document are considered to be in the same series. Thus, any new version, translation, etc. of a pre-existing document should inherit the seriesid of the original document.
ScrollKeeper uses the seriesid to identify documents which are equivalent to each other. For example, ScrollKeeper can merge the contents lists from two locales. ScrollKeeper uses the seriesid to guarantee that a given document is not listed twice, once in each locale.
To generate a new unique seriesid, use the scrollkeeper-gen-seriesid command.
ScrollKeeper has also added an attribute to the "subject" element, called "category". The category element is used to classify the topic of the document according to subject. ScrollKeeper uses this attribute to place the document in one or more positions in the Table of Contents, which lists all the documents sorted by subject.
The category list is heirarchical, consisting of main categories, subcategories, subsubcategories, etc. The category levels are seperated with pipes (|). For example, a document which is part of the core desktop of GNOME has a category of "GNOME|Core Desktop".
Note that there is a controlled list of categories. The categories are installed in an XML file called scrollkeeper_cl.xml. The category file for the C locale can typically be found at /usr/share/scrollkeeper/Templates/C/scrollkeeper_cl.xml. There is an XSLT stylesheet (categories.xml) which will convert this into an HTML file to make it more readable. To do the conversion, use xsltproc -o categories.html /usr/share/scrollkeeper/stylesheets/categories.xsl /usr/share/scrollkeeper/Templates/C/scrollkeeper_cl.xml. Note that the exact paths to categories.xsl and scrollkeeper_cl.xml may vary depending on distribution.
The standard OMF specifies the "language" element as optional and as having no attributes. For ScrollKeeper to relate documents with the locale of the user, the locale of the documents must be specified. This is done by using a new attribute, "code", of the "language" element. The language code should be a standard locale.
The standard OMF specifies the "identifier" element as optional and as having no attributes. For ScrollKeeper to work properly, the "identifier" element is mandatory and must have the "url" attribute which points to a copy of the file on a locally accessible filesystem.
The standard OMF specifies the "format" element as optional and as having an optional attribute, "mime". For ScrollKeeper to extract metadata from DocBook documents, the correct mime type must be provided.
Common mime types include "text/xml", "text/sgml", and "text/html". ScrollKeeper will not attempt to extract extra metadata (such as the table of contents or index) from documents in other mime types. ScrollKeeper will catalog documents in any mime type according to the information provided in the OMF file.