ScrollKeeper: Open Source Document Management
by Kendall Grant Clark | Pages: 1, 2, 3

Hacking ScrollKeeper

System administrators often need to write quick and dirty scripts and tiny applications to automate some onerous task or to support some local policy or convention. Most package management frameworks, like RPM and DEB, provide an API for manipulating the installed base of packages. ScrollKeeper provides a similar facility for working with system documentation.

ScrollKeeper's use of lowest common denominator technology makes it ideal for sysadmin hacking, as well as for integrating with a variety of Internet and intranet web tools. If your intranet uses XSLT to render documents for web browsing, presenting a catalog of system documentation is as simple as calling scrollkeeper-get-extended-contents-list and applying a stylesheet to the result.

Likewise, if your organization uses DocBook for documentation, integrating locally produced documents -- for example, a departmental policies and procedures or operations manual -- into the help browser of GNOME desktops becomes a fairly trivial matter. This technique is especially helpful in document-rich organizations -- university academic departments, research laboratories, policy think-tanks -- where easy and ready access to standard documents is crucial.

As a routine part of installing and updating desktop and applications software on user machines, a sysadmin merely creates, say, a Debian package, which contains, for example, the latest operations and safety manuals. She also creates an OMF metadata instance for each manual included in the package. As part of the package installation routine, the package manager registers each manual with ScrollKeeper, which it can do by calling

scrollkeeper-install [manual_title]-[locale].omf

or, if the package is upgrading an existing package, by calling

scrollkeeper-uninstall [manual_title]-[locale].omf

first.

It's a good idea to use a directory under /usr/local to store local OMF instances, which can be done by setting the OMF_DIR environment variable.

An OMF instance for a locally-produced documentation resource might look something like the following.

     <omf>
      <resource>
       <title> US DOD BLU-82 "Daisy Cutter" Operations Manual</title>

       <creator>
         <person>
           <firstName>Dr.</firstName>
           <lastName>Strangelove</lastName>
           <email>drstrangelove@pentagon.dod.gov</email>
         </person>
       </creator>

       <subject>
         <category>System|Other</category>
       </subject>

       <description>
        This document describes the BLU-82 mass area demolition and
        anti-personnel munition, aka, the "Daisy Cutter". BLU-82
        combines a watery mixture of ammonium nitrate and aluminum
        with air, then ignites the mist for a huge explosion that
        incinerates everything within 600 yards. The shock wave can be
        felt miles away.

        First created during the Vietnam War to quickly clear jungle
        landing zones, the daisy cutter was used against Iraqi troops
        during the Gulf War. Recent reports from the ground in
        Afghanistan indicate the huge bombs have been used against
        front-line Taliban positions. The BLU-82 costs about $27,000
        each. They are dropped from a C-130 cargo plane flying at
        least 6,000 feet off the ground, to avoid the bomb's massive
        shock wave. Each is more than 17 feet long and 5 feet in
        diameter - about the size of a VW Beetle but far heavier.

       </description>
       <type>manual</type>
       <format mime="text/sgml"/>
       <identifier 
           url="/usr/local/share/really/big/bombs/daisycutter-manual.sgml"/>
       <language code="C"/>
      </resource>
     </omf>

The Future of ScrollKeeper

Like most open source projects, ScrollKeeper has an ambitious plan for future expansion and, from the looks of it, could use more help. In the short term internationalization and localization improvements are planned, as well as improved searching and indexing functionality. In the longer term, ScrollKeeper may expand to deal with non-local documents and resources, including using a remote OMF server for synchronizing LAN, WAN, and Internet-wide document collections, and so on.

The way ScrollKeeper uses XML is neither novel nor cutting-edge. In fact, it's rather ordinary, even pedestrian. And that's exactly the point. ScrollKeeper's utility lies not in the way it uses XML, but that, by using XML, it allows developers, admins, and others to leverage existing XML tools and knowledge to manage document collections; that it makes possible the creation and growth of useful metadata, which aids both document producers and consumers; and that it does so in a relatively simple and easy to understand way. In the final estimation, surely that is what makes XML a good and useful thing.

---