Testing Your OMF File

Once you've written an OMF file, you should test it to make sure that it works. To test an OMF file:

  1. Make sure you have ScrollKeeper installed. You can always get it from http://sourceforge.net/projects/scrollkeeper. The stable releases have an even minor revision numer, such as 0.2.x or 0.4.x. The unstable, development releases have odd minor revision numbers such as 0.1.x and 0.3.x. You probably want the latest stable release.

  2. Next you should make sure the url specified in the identifier element is accurate and points to a valid document.

  3. Now you should have ScrollKeeper process the OMF file and the document it points to. You can do this without having root access or affecting the primary ScrollKeeper catalog on your system by using the -p flag to scrollkeeper-install. For example: scrollkeeper-install -v -p testomf_db_dir testomf.omf This will read the OMF file called testomf.omf and create a new ScrollKeeper catalog in the directory testomf_db_dir. The -v flag indicates that it should be run in verbose mode, sending all warnings and errors to standard output. If you are not logged in as root, you will see an error stating that you do not have permission to make an entry in the log file. You can ignore this error. If you do not see any other errors, then no errors or warnings occurred while processing the OMF file or document.

  4. If you are curious or would like to confirm that the catalog files look alright, you may look at them directly. This step isn't necessary, but may be interesting or help debugging in the case that errors occur. The full explanation of these files are beyond the scope of this document. Briefly:

    1. testomf_db_dir/scrollkeeper_docs should contain a single line for each resource entry in the OMF file. The first document will be given an identifying number in the second column. This will be 0 since it is the first document.

    2. testomf_db_dir/TOC/0 should contain the table of contents for the first document. If the document is not in DocBook/XML, the table of contents will not exist.

    3. testomf_db_dir/index/0 should contain the index for the first document. If the document is not in DocBook/XML or does not have indexterms in it, the index will not exist.

    4. testomf_db_dir/index/locale/scrollkeeper_cl.xml should be the standard ScrollKeeper contents list for the locale, taken directly from the template for the locale, with a single entry for each document listed in the OMF file. You can verify that each document appears in the correct category.

  5. Now you are finished and can delete the temporary catalog testomf_db_dir.

If you have ScrollKeeper version 0.3.7 or later, you can validate your OMF file against the ScrollKeeper-OMF DTD. This will tell you if your OMF file follows the rules specified in the DTD in terms of structure of the XML file. Note that ScrollKeeper 0.3.7 and later will ignore any OMF files which do not validate against the DTD. To validate your OMF file, issue a command similar to:

      xmllint --noout --valid foo-C.omf
Thanks to the magic of XML catalogs, it should find the DTD specified in the OMF file on your computer (instead of going onto the internet to find the DTD) and validate the OMF file.