In this section, I explain the overall process used in the installation and registration process, the files involved, how to configure the package, and a step-by-step list of how to set up a module.


Here I will assume you have a package and one or more documents which you would like to install as part of the package and register with ScrollKeeper. In this section, I explain the overall concept of what needs to be done. In the following sections, I explain the details of how this is done.

During application development, we need to do the following:

  • Write an OMF file for each document. The documentation author must write an OMF file for each document. Each OMF file describes the basic document metadata, such as title, author, language, and format.

  • Write a simple Makefile for each document. To aid the build system, the documentation author or a hacker must write a very simple Makefile which merely defines a few variables which is needed by the standard Makefile.

  • Set up general build and configure scripts. Small changes must be made to a handful of build and configure files to make everything work together properly.

During package configure and build, we need to achieve the following:
  • Complete the OMF files. Part of the OMF file, the URL for the document file, is not known until configure time. (For the cases discussed in this example package, this URL is a path to a file on the local machine.) Thus, the OMF file is completed at build time to include the final, correct URL for the document.

  • Install the OMF files. The OMF files are installed on the user's system in a special location, typically under $prefix/share/omf, where ScrollKeeper knows to find the OMF files. The documents themselves can be installed anywhere since the OMF file has the URL of the documents.

  • Install the documentation. The documents can be installed anywhere on the system, since the OMF files direct ScrollKeeper to the documents' paths.

  • Register with ScrollKeeper After installation (or uninstallation), a ScrollKeeper script is executed which looks for added, modified, or removed files in the OMF directory(ies) and update its catalog. This way the catalog is modifed at install and uninstall time (typically by root, who has ownership of the database for a typical install) instead of at the run time of the application (with permissions of the end-user) which requests the metadata.


While there are many ways one may configure a package to install its documents and register them with ScrollKeeper, we describe here the way this example package is done. It was designed to be as simple as possible, so it is recommended that most packages follow this form. It has the following files of interest:

You should include the test for ScrollKeeper, since a user will need ScrollKeeper installed in order to build a package which registers its documentation with ScrollKeeper. (Note however that the package will not require that ScrollKeeper is installed to use the package. This is merely a requirement to properly build the package, not to install or run the applications in it.)

Don't forget to include a SCROLLKEEPER_BUILD_REQUIRED variable if you plan to create binary packages, such as RPMs.

You will need to make small edits to several files.


This Makefile includes the instructions for adding the URL to the OMF file, installing the OMF file, and executing the script to register the document with ScrollKeeper. It should not require any modifications.


This Makefile includes the instructions for installing (and uninstalling) XML documents and their figures. It includes omf.make to handle the OMF files. It should not require any modifications.


Thanks to doc/xmldocs.make this Makefile contains merely a handful of variable definitions. See the comments at the top of doc/xmldocs.make for the definitions of each of these variables.


This is the OMF file, typically written by the document author, containing the document metadata.


This is only of interest if you are building RPMs. You will need to include:

if which scrollkeeper-update>/dev/null 2>&1; then scrollkeeper-update -q -o %{_datadir}/omf/scrollkeeper-example2; fi

if which scrollkeeper-update>/dev/null 2>&1; then scrollkeeper-update -q; fi
Notice that this will allow your package to install properly on systems which do not have ScrollKeeper on them. If the user later installs ScrollKeeper, the standard ScrollKeeper catalog build process it performs at install time will automatically find the OMF files from your package and register the documents.

That is it. I don't have any instructions on making Debian packages, but if anybody would like to send me info, I'd be happy to include it.

Step-By-Step Instructions

To add documentation, OMF files, and build instructions to an existing package, simply follow the following steps. Consult the appropriate example files in this package (scrollkeeper-example2) for details and examples.

  1. Update You should add a test for ScrollKeeper (via. scrollkeeper-config), since ScrollKeeper is needed to build the package:
    dnl ====================================
    dnl = Begin tests for scrollkeeper
    dnl ====================================
    if test x$SK_CONFIG = xno; then
      AC_MSG_ERROR(Couldn't find scrollkeeper-config. Please install the scrollkeeper package:
    dnl ====================================
    dnl = End tests for scrollkeeper
    dnl ====================================
    You should also declare SCROLLKEEPER_BUILD_REQUIRED since RPM users will need this variable:
    You will also need to add doc/Makefile to AC_OUTPUT, and similar entries for each subdirectory you create. For example:
    You will need to add an entry in AC_OUTPUT for each which you create below.
  2. Add COPYING-DOCS Create COPYING-DOCS in the toplevel directory. This file should contain the license of your documentation.

  3. Modify Put COPYING-DOCS into EXTRA_DIST and doc into SUBDIRS.

  4. Create and populate doc directory Create the doc subdirectory of the toplevel directory if it does not exist, and copy omf.make and xmldocs.make into it.
  5. Create doc/ List each document directory you will create in SUBDIRS. should also declare
    EXTRA_DIST= xmldocs.make omf.make
    so that these files are included in tarballs of the package.
  6. Create document subdirectories Create directories in doc for each document. In each of these directories, create a subdirectory for each locale the document occurs in. In all of these directories, be sure to include a simple file listing each subdirectory in SUBDIRS. Make sure each is represented in the AC_OUTPUT section of
  7. Add documents, figures, and OMF files Put the documents, figures, and OMF files into the appropriate directories, one document and OMF file per directory. (For information on writing OMF files, see Writing ScrollKeeper OMF Files.) Note that the URL listed in the OMF file can be an empty string, since it will be over-written with the real URL at build time.
  8. Write for each document Each document directory requires a It is comprised primarily of a short list of variables. Use the from the scrollkeeper-example2 package and modify it as appropriate, following the instructions in xmldocs.make. Here is the file from scrollkeeper-example2:
    figdir = figures
    docname = scrollkeeper-example2-manual
    lang = C
    omffile = scrollkeeper-example2-manual-C.omf
    entities = legal.xml fdl-appendix.xml
    include $(top_srcdir)/doc/xmldocs.make
    dist-hook: app-dist-hook
  9. Update the RPM spec file If necessary, update the spec file for creating RPMs. You will need to add
    BuildRequires:   scrollkeeper >= @SCROLLKEEPER_BUILD_REQUIRED@
    if which scrollkeeper-update>/dev/null 2>&1; then scrollkeeper-update -q -o %{_datadir}/omf/scrollkeeper-example2; fi
    if which scrollkeeper-update>/dev/null 2>&1; then scrollkeeper-update -q; fi
    (Be sure to replace "scrollkeeper-example2" with the name of your package.) You will also need to update the %files section. You will need to add COPYING-DOCS to the %doc line. You will also need to add lines similar to:
    but with your package name in place of "scrollkeeper-example2".


The install step installs the OMF files and then calls scrollkeeper-update -p $(scrollkeeper_localstate_dir) -o $(DESTDIR)$(omf_dest_dir) (see doc/omf.make). The reason we must pass it scrollkeeper_localstate_dir is that when we are building packages such as RPMs, we want it to generate a new database under the build root, and not try to update the system's database. This flag gives us a mechanism to pass the path to the database which will include the build root if a package is being built. (The second flag and option indicates that scrollkeeper-update should only look in the OMF directory for this particular package to update the catalog. This is done to speed up execution.)

The consequence of passing scrollkeeper_localstate_dir is that one must be sure that the path points to the correct database on the system. For FHS-compliant systems such as Linux, this is /var/lib/scrollkeeper. Thus, you will need to run configure with --localstatedir=/var. (Or you could adjust doc/omf.make so that scrollkeeper_localstate_dir points to /var/lib/scrollkeeper with the localstatedir you use if necessary.)