<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "0.3.13">
  <!ENTITY manrevision "1.1">
  <!ENTITY date "Jun 2003">
  <!-- Information about the entities
       The legal.xml file contains legal information, there is no need to edit the file. 
       Use the appversion entity to specify the version of the application.
       Use the manrevision entity to specify the revision number of this manual.
       Use the date entity to specify the release date of this manual.
       Use the app entity to specify the name of the application. -->
]>
<!-- =============Document Header ============================= -->
<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo> 
    <title>Writing ScrollKeeper OMF Files V&manrevision;</title>       

    <copyright> 
      <year>2002</year> 
      <holder>Dan Mueth</holder> 
    </copyright> 
<!-- translators: uncomment this:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (LANGUAGE translation)</holder>
  </copyright>

   -->
<!-- An address can be added to the publisher information.  If a role is 
     not specified, the publisher/author is the same for all versions of the 
     document.  -->
<!--
    <publisher> 
      <publishername> GNOME Documentation Project </publishername> 
    </publisher> 
   -->

   &legal;

   <!-- This file  contains link to license for the documentation (GNU FDL), and 
        other legal stuff such as "NO WARRANTY" statement. Please do not change 
	any of this. -->

    <authorgroup> 
      <author> 
	<firstname>Dan</firstname> 
	<surname>Mueth</surname> 
	<affiliation> 
<!--
	  <orgname>GNOME Documentation Project</orgname> 
  -->
	  <address> <email>muet@alumni.uchicago.edu</email> </address> 
	</affiliation> 
      </author> 
<!-- This is appropriate place for other contributors: translators,
      maintainers,  etc. Commented out by default.
       <othercredit role="translator">
	<firstname>Latin</firstname> 
	<surname>Translator 1</surname> 
	<affiliation> 
	  <orgname>Latin Translation Team</orgname> 
	  <address> <email>translator@gnome.org</email> </address> 
	</affiliation>
	<contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>


<!-- According to GNU FDL, revision history is mandatory if you are -->
<!-- modifying/reusing someone else's document.  If not, you can omit it. -->
<!-- Remember to remove the &manrevision; entity from the revision entries other
-->
<!-- than the current revision. -->
    <revhistory>
      <revision> 
	<revnumber>Writing ScrollKeeper OMF Files V1.0</revnumber> 
	<date>Feb 2002</date> 
	<revdescription> 
	  <para role="author">Dan Mueth
	    <email>muet@alumni.uchicago.edu</email>
	  </para>
	</revdescription> 
      </revision> 
      <revision> 
	<revnumber>Writing ScrollKeeper OMF Files V&manrevision;</revnumber> 
	<date>&date;</date> 
	<revdescription> 
	  <para role="author">Malcolm Tredinnick
	    <email>malcolm@commsecure.com.au</email>
	  </para>
	  <para>
	    Brought up to date for recent releases.
	  </para>
	</revdescription> 
      </revision> 
    </revhistory> 

    <releaseinfo>This manual describes how to write OMF files for use with
      ScrollKeeper version &appversion;.
    </releaseinfo>

<!--
    <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the ScrollKeeper or
	this manual, please use the ScrollKeeper bug tracker and/or mailing
        lists at <ulink url="http://scrollkeeper.sourceforge.net" 
        type="http">the ScrollKeeper web page</ulink>. 
      </para>
    </legalnotice> 
-->

  </articleinfo> 

  <indexterm zone="index"> 
    <primary>ScrollKeeper</primary> 
    <secondary>OMF Files</secondary> 
  </indexterm> 
  <indexterm zone="index"> 
    <primary>OMF Files</primary> 
    <secondary>Writing</secondary> 
  </indexterm>

<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->
  <sect1 id="skomf-introduction"> 
    <title>Introduction</title> 
    <para>
      An OMF file provides metadata for one or more documentation files.
      This metadata includes various useful information which may be used
      for cataloging the documents, including the author, title, 
      document file location, version, locale, and various other information.
      ScrollKeeper uses this metadata, along with metadata extracted directly
      from documents, to create a documentation catalog which can be used
      by documentation and help browsers.
    </para> 
    <para>
      This document describes the form and fields of an OMF file.  It is meant
      to be a simple reference for an OMF file author at any level.  Feel
      free to jump around through the sections to quickly find the information 
      you need.
    </para> 
  </sect1>


<!-- =========== About the OMF ============================== -->
  <sect1 id="skomf-abouttheomf"> 
    <title>About the OMF</title> 
    <para>
      The <ulink type="http" url="http://www.ibiblio.org/osrt/omf/">Open 
      Metadata Framework (OMF)</ulink> is an open standard for describing
      documentation metadata, based on the Dublin Core metadata set.
      The OMF was created by the <ulink type="http"
      url="http://www.ibiblio.org">Metalab</ulink> project to catalog 
      open source documentation.  The OMF is described by only 16 elements
      to keep it simple and easy to use.
    </para>
  </sect1>


<!-- =========== The Standard OMF Elements ============================== -->
  <sect1 id="skomf-standardomf"> 
    <title>Standard OMF Elements</title> 
    <indexterm>
      <primary>OMF</primary> 
      <secondary>Standard Elements</secondary> 
    </indexterm> 
    <indexterm>
      <primary>ScrollKeeper</primary> 
      <secondary>OMF</secondary> 
      <tertiary>Standard Elements</tertiary> 
    </indexterm> 
    <para>
      There are 16 standard OMF elements.  The authoritative definition of
      the OMF is on the <ulink url="http://www.ibiblio.org/osrt/omf/omf_elements"
      type="http">OMF element web page</ulink>.  It is reproduced here
      (as of Feb 14, 2002) for your convenience. 
    </para>
    <para>
      The 16 standard OMF elements, along with their obligation, repeatability, and 
      standard attributes are summarized below:
      <informaltable frame="all">
        <tgroup cols="5">
          <tbody>
            <row>
              <entry>
                NUMBER
              </entry>
              <entry>
                LABEL
              </entry>
              <entry>
                OBLIGATION
              </entry>
              <entry>
                REPEATABILITY
              </entry>
              <entry>
                ATTRIBUTES
              </entry>
            </row>
            <row>
              <entry>
                1.
              </entry>
              <entry>
                creator
              </entry>
              <entry>
                mandatory
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                2.
              </entry>
              <entry>
                maintainer
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                3.
              </entry>
              <entry>
                contributor
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                4.
              </entry>
              <entry>
                title
              </entry>
              <entry>
                mandatory
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                5.
              </entry>
              <entry>
                date
              </entry>
              <entry>
                mandatory
              </entry>
              <entry>
                not repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                6.
              </entry>
              <entry>
                version
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                id, date, description
              </entry>
            </row>
            <row>
              <entry>
                7.
              </entry>
              <entry>
                subject
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                8.
              </entry>
              <entry>
                description
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                9.
              </entry>
              <entry>
                type
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                10.
              </entry>
              <entry>
                format
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                dtd, mime
              </entry>
            </row>
            <row>
              <entry>
                11.
              </entry>
              <entry>
                identifier
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                12.
              </entry>
              <entry>
                source
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                13.
              </entry>
              <entry>
                language
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                14.
              </entry>
              <entry>
                relation
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                (none)
              </entry>
            </row>
            <row>
              <entry>
                15.
              </entry>
              <entry>
                coverage
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                geographic, distribution, kernel, architecture, os
              </entry>
            </row>
            <row>
              <entry>
                16.
              </entry>
              <entry>
                rights
              </entry>
              <entry>
                optional
              </entry>
              <entry>
                repeatable
              </entry>
              <entry>
                type, license, license.version, holder
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </para>
    <para>
      The elements are defined as follows:
      <informaltable frame="all">
        <tgroup cols="3">
          <tbody>
            <row>
              <entry>
                NUMBER
              </entry>
              <entry>
                LABEL
              </entry>
              <entry>
                DEFINITION
              </entry>
            </row>
            <row>
              <entry>
                1.
              </entry>
              <entry>
                creator
              </entry>
              <entry>
The person or organization primarily responsible for creating the
intellectual content of the resource. CREATOR should appear in RFC822
format (http://info.internet.isi.edu:80/in-notes/rfc/files/rfc822.txt).
Preferred format: mailname@site.domain.top (Full Name)
              </entry>
            </row>
            <row>
              <entry>
                2.
              </entry>
              <entry>
                maintainer
              </entry>
              <entry>
The person or organization responsible for publishing the resource in its
current form.  If left blank, this value defaults to CREATOR. (RFC822 format)
              </entry>
            </row>
            <row>
              <entry>
                3.
              </entry>
              <entry>
                contributor
              </entry>
              <entry>
A person or organization not specified in a CREATOR or MAINTAINER element
who has made significant intellectual contributions to the resource but
whose contribution is secondary to any person or organization specified in
a CREATOR or MAINTAINER element.  (RFC822 format)
              </entry>
            </row>
            <row>
              <entry>
                4.
              </entry>
              <entry>
                title
              </entry>
              <entry>
The name given to the resource by the CREATOR or MAINTAINER.
              </entry>
            </row>
            <row>
              <entry>
                5.
              </entry>
              <entry>
                date
              </entry>
              <entry>
The date on which the resource was made available in its current form.
(Recommended best practice is an 8 digit number in the form YYYY-MM-DD
as defined in http://www.w3.org/TR/NOTE-datetime, a profile of ISO 8601. In
this scheme, the date element 1994-11-05 corresponds to November 5, 1994.)
              </entry>
            </row>
            <row>
              <entry>
                6.
              </entry>
              <entry>
                version
              </entry>
              <entry>
VERSION is a multifaceted element, consisting of three attributes.
VERSION.id consists of a string or number that distinguishes the 
current revision of the resource from other revisions.  VERSION.date records 
the date the resource was made available in the form specified by
VERSION.id.  (Recommended best practice is an 8 digit number in the
form YYYY-MM-DD as defined in http://www.w3.org/TR/NOTE-datetime, a profile 
of ISO 8601. In this scheme, the date element 1994-11-05 corresponds to
to November 5, 1994.)  VERSION.description summarizes revisions that 
distinguish VERSION.id from other versions of the resource.  Repeated 
instances of VERSION comprise the revision history of a resource.
              </entry>
            </row>
            <row>
              <entry>
                7.
              </entry>
              <entry>
                subject
              </entry>
              <entry>
The topic of the resource. Typically, this element employs keywords that
summarize the subject or content of the resource.
              </entry>
            </row>
            <row>
              <entry>
                8.
              </entry>
              <entry>
                description
              </entry>
              <entry>
A textual description of the content of the resource (e.g., an abstract, 
contents note).
              </entry>
            </row>
            <row>
              <entry>
                9.
              </entry>
              <entry>
                type
              </entry>
              <entry>
The category of the resource.  To promote consistency, TYPE
should be selected from the following list: HOWTO, mini-HOWTO, user's guide, 
administrator's guide, programmer's guide, installation guide.
              </entry>
            </row>
            <row>
              <entry>
                10.
              </entry>
              <entry>
                format
              </entry>
              <entry>
Details about the implementation of the resource.  FORMAT accomodates two
attributes: FORMAT.DTD and FORMAT.MIME. 
FORMAT.DTD describes the document type definition used in the resource (if
any).  FORMAT.MIME should be expressed as a MIME type, as defined in RFC 
2046 (http://info.internet.isi.edu:80/in-notes/rfc/files/rfc2046.txt).
e.g.:  type/subtype.  
              </entry>
            </row>
            <row>
              <entry>
                11.
              </entry>
              <entry>
                identifier
              </entry>
              <entry>
A specification of a unique ID by which the resource may be
identified and from which the resource may be retrieved. Entries for
this field should contain a valid URL which returns the resource in
question. For example:
          http://www.ldp.org/docs/howto/nfs
              </entry>
            </row>
            <row>
              <entry>
                12.
              </entry>
              <entry>
                source
              </entry>
              <entry>
A specification of any previous or alternative publication of the
resource in its current form (e.g. a larger work from which the resource is 
extracted, such as a chapter taken from a book).  SOURCE may include a URL, 
ISBN or similar device. 
              </entry>
            </row>
            <row>
              <entry>
                13.
              </entry>
              <entry>
                language
              </entry>
              <entry>
Language(s) of the intellectual content of the resource. Where practical,
the content of this field should coincide with RFC 1766. See:
http://ds.internic.net/rfc/rfc1766.txt 
              </entry>
            </row>
            <row>
              <entry>
                14.
              </entry>
              <entry>
                relation
              </entry>
              <entry>
A URL that points to the IDENTIFIER element of another resource.  Each
instance of RELATION links the resource to other resources of similar
domain or style.
              </entry>
            </row>
            <row>
              <entry>
                15.
              </entry>
              <entry>
                coverage
              </entry>
              <entry>
A multifaceted description of the resource's intellectual scope that consists 
of five attributes. COVERAGE.geographic identifies regional specificity of the 
resource.  Where practical COVERAGE.geographic should be expressed as an ISO 
3166-compliant string of two characters 
(See http://www.w3.org/International/O-misc-iso3166.html). COVERAGE.distribution
identifies a Linux distribution explicitly specified in the resource.  
COVERAGE.kernel identifies the kernel version treated in the resource.  
COVERAGE.architecture identifies hardware described in the resource.  
COVERAGE.os identifies an operating system explicitly specified in the resource.
              </entry>
            </row>
            <row>
              <entry>
                16.
              </entry>
              <entry>
                rights
              </entry>
              <entry>
An indication of the copying policy under which the resource is distributed.  
Four attributes comprise the RIGHTS element.  RIGHTS.type identifies the name 
of the resource's distribution license.  To promote consistency, RIGHTS.type 
should be selected from the following list:  GNU GPL, GNU LGPL, BSD, X 
Consortium, Artistic, MPL, QPL, IBMPL, ASPL, libpng, zlib, IJG JPEG, OPL, ORL.
RIGHTS.license identifies the URL for the license referenced in RIGHTS.type.  
RIGHTS.license.version identifies the version number of the resource's license.
RIGHTS.holder identifies the person or organization who holds the rights for 
the resource described in RIGHTS.license.
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </para>
    <para>
      Please note that these are the standard OMF elements.  ScrollKeeper
      makes a couple small extensions to the OMF, as described in the next
      section.
    </para>
  </sect1>


<!-- =========== Special ScrollKeeper Extensions ============================== -->
  <sect1 id="skomf-specialscrollkeeperextensions"> 
    <title>Special ScrollKeeper Extensions</title> 
    <indexterm>
      <primary>OMF</primary> 
      <secondary>ScrollKeeper Extensions</secondary> 
    </indexterm> 
    <indexterm>
      <primary>ScrollKeeper</primary> 
      <secondary>OMF Extensions</secondary> 
    </indexterm> 
    <para>
      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.
    </para>
    <sect2 id="skomf-seriesid">
      <title>Document Series ID (seriesid)</title>
      <indexterm>
        <primary>OMF</primary> 
        <secondary>seriesid</secondary> 
      </indexterm> 
      <indexterm>
        <primary>ScrollKeeper</primary> 
        <secondary>OMF</secondary> 
        <tertiary>seriesid</tertiary> 
      </indexterm> 
      <para>
        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. 
      </para>
      <para>
        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.
      </para>
      <indexterm>
        <primary>ScrollKeeper</primary> 
        <secondary>scrollkeeper-gen-seriesid</secondary> 
      </indexterm> 
      <para>
        To generate a new unique seriesid, use the 
        <command>scrollkeeper-gen-seriesid</command> command.
      </para>
    </sect2>
    <sect2 id="skomf-category">
      <title>Category</title>
      <indexterm>
        <primary>OMF</primary> 
        <secondary>Category</secondary> 
      </indexterm> 
      <indexterm>
        <primary>ScrollKeeper</primary> 
        <secondary>OMF</secondary> 
        <tertiary>Category</tertiary> 
      </indexterm> 
      <para>
        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.
      </para> 
      <para> 
        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".
      </para> 
      <para> 
        Note that there is a controlled list of categories.
        The categories are installed in an XML file called
        <filename>scrollkeeper_cl.xml</filename>.  The category file for the C
        locale can typically be found at 
        <filename>/usr/share/scrollkeeper/Templates/C/scrollkeeper_cl.xml</filename>.
	There is an XSLT stylesheet (<filename>categories.xml</filename>) 
        which will convert this into an HTML file to make it more readable.
	To do the conversion, use <command>xsltproc -o categories.html /usr/share/scrollkeeper/stylesheets/categories.xsl /usr/share/scrollkeeper/Templates/C/scrollkeeper_cl.xml</command>.  Note that the exact paths to <filename>categories.xsl</filename>
        and <filename>scrollkeeper_cl.xml</filename> may vary depending on
        distribution.
      </para> 
<!--	Commenting this out until it is implemented, which it isn't :(
      <para> 
        Note that each category is identified according to an attribute which
        is locale-independent.  Thus, the OMF file for a document in
        another locale can specify the category in that locale or in C.
        ScrollKeeper will use the category attribute to translate the
        category into the appropriate locale if necessary.  It is
        best to always specify the category in the C locale to avoid
        errors or incompatibilities if the translation of the category
        name changes.
      </para> 
-->
    </sect2>     
    <sect2 id="skomf-languagecode">
      <title>Language Code</title>
      <indexterm>
        <primary>OMF</primary> 
        <secondary>Language Code</secondary> 
      </indexterm> 
      <indexterm>
        <primary>ScrollKeeper</primary> 
        <secondary>OMF</secondary> 
        <tertiary>Language Code</tertiary> 
      </indexterm> 
      <para>
        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.
      </para>
    </sect2>     
    <sect2 id="skomf-url">
      <title>URL</title>
      <indexterm>
        <primary>OMF</primary> 
        <secondary>URL</secondary> 
      </indexterm> 
      <indexterm>
        <primary>ScrollKeeper</primary> 
        <secondary>OMF</secondary> 
        <tertiary>URL</tertiary> 
      </indexterm> 
      <para>
        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.
      </para>
    </sect2>     
    <sect2 id="skomf-mime">
      <title>Mime Type</title>
      <indexterm>
        <primary>OMF</primary> 
        <secondary>Mime Type</secondary> 
      </indexterm> 
      <indexterm>
        <primary>ScrollKeeper</primary> 
        <secondary>OMF</secondary> 
        <tertiary>Mime Type</tertiary> 
      </indexterm> 
      <para>
        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.
      </para>
      <para>
        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.
      </para>
    </sect2>     
  </sect1>


<!-- =========== A Minimal OMF File ============================== -->
  <sect1 id="skomf-minimalomf"> 
    <title>A Minimal OMF File</title> 
    <indexterm>
      <primary>OMF</primary> 
      <secondary>Examples</secondary> 
      <tertiary>Minimal</tertiary> 
    </indexterm> 
    <para>
     In this section, we present the simplest OMF file which obeys the
     OMF scheme and which allows ScrollKeeper &appversion; to properly
     function.  Note that while the OMF is not XML-specific, ScrollKeeper
     requires that OMF files be in XML.
    </para>
    <para>
      Here is an example of the most minimal OMF file, containing metadata
      for only one document:
<programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE omf PUBLIC "-//OMF//DTD Scrollkeeper OMF Variant V1.0//EN" "http://scrollkeeper.sourceforge.net/dtds/scrollkeeper-omf-1.0/scrollkeeper-omf.dtd"&gt;
&lt;omf&gt;
  &lt;resource>
    &lt;creator>
      kenny@gnome.org (Kenny Graunke)
    &lt;/creator>
    &lt;title>
      Gfloppy Manual
    &lt;/title>
    &lt;date>
      2001-11-23
    &lt;/date>
    &lt;subject category="GNOME|Core Desktop"/>
    &lt;format mime="text/xml"/>
    &lt;identifier url="file://usr/share/doc/gfloppy/gfloppy.xml"/>
    &lt;language code="C"/>
    &lt;relation seriesid="01ddeea4-0a42-11d6-9cf9-ee43c422358d"/>
  &lt;/resource>
&lt;/omf>
</programlisting>
    </para>
    <para>
      All OMF files which are to be used with ScrollKeeper should have all
      of these elements.  Make sure that the category is valid, chosen
      from the controlled list.  The seriesid should be unique from all
      other documents except different versions, locales, or formats of
      the same document.
    </para>
    <para>
      Multiple documents can be described in a single OMF file by placing
      multiple "resource" objects in the file.
    </para>
    <para>
      Note that the URL is typically not known until build or install time.
      Thus, a placeholder or estimated location is often used in the original
      OMF file.  When the package is built, the correct file location is
      automatically substituted into the OMF file using
      <command>scrollkeeper-preinstall</command>.
    </para>
    <sect2 id="skomf-minimalomf-encoding">
      <title>Encoding</title>
      <para>
        Note that you should always include the document's encoding in the
        XML declaration since there is no good way to detect a document's
        encoding.  ScrollKeeper uses the libxml libraries, which supports
        the following encodings: UTF-8, UTF-16, ISO-8859-1 (ISO-Latin-1),
        ASCII, HTML. For more information, see <ulink type="http"
        url="http://xmlsoft.org/encoding.html">Libxml Encoding Support
        Web Pages</ulink>. 
      </para>
    </sect2>
  </sect1>


<!-- =========== A Complete OMF File ============================== -->
  <sect1 id="skomf-completeomf"> 
    <title>A Complete OMF File</title> 
    <indexterm>
      <primary>OMF</primary> 
      <secondary>Examples</secondary> 
      <tertiary>Complete</tertiary> 
    </indexterm> 
    <para>
      A complete OMF file will include all of the relevant elements and
      attributes specified by the OMF scheme, along with the extensions
      required by ScrollKeeper.  It is a good idea to include these 
      optional elements and attributes since ScrollKeeper will provide
      support for many of them in the future.
    </para>
    <para>
      Here is an example of a complete OMF file, containing metadata
      for almost all of the OMF elements for only one document:
<programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE omf PUBLIC "-//OMF//DTD Scrollkeeper OMF Variant V1.0//EN" "http://scrollkeeper.sourceforge.net/dtds/scrollkeeper-omf-1.0/scrollkeeper-omf.dtd"&gt;
&lt;omf&gt;
  &lt;resource>
    &lt;creator>
      kenny@gnome.org (Kenny Graunke)
    &lt;/creator>
    &lt;maintainer>
      kenny@gnome.org (Kenny Graunke)
    &lt;/maintainer>
    &lt;contributor>
      jrb@redhat.com (Jonathan Blandford)
    &lt;/contributor>
    &lt;contributor>
      hobbit@aloss.ukuu.org.uk (Telsa Gwynne)
    &lt;/contributor>
    &lt;title>
      Gfloppy Manual
    &lt;/title>
    &lt;date>
      2001-11-23
    &lt;/date>
    &lt;version identifier="1.0.2" date="2001-11-23" description="Updated for Gfloppy 1.0.1"/>
    &lt;subject category="GNOME|Core Desktop"/>
    &lt;description>
      User manual for the Gfloppy application. 
    &lt;/description>
    &lt;type>
      user's guide
    &lt;/type>
    &lt;format mime="text/xml" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
    &lt;identifier url="file://usr/share/doc/gfloppy/gfloppy.xml"/>
    &lt;language code="C"/>
    &lt;relation seriesid="01ddeea4-0a42-11d6-9cf9-ee43c422358d"/>
    &lt;rights type="GNU FDL" license.version="1.1" holder="Kenny Graunke"/>
  &lt;/resource>
&lt;/omf>
</programlisting>
    </para>
  </sect1>

<!-- =========== TESTING YOUR OMF FILE ============================== -->
  <sect1 id="skomf-testing"> 
    <title>Testing Your OMF File</title> 
    <indexterm>
      <primary>OMF</primary> 
      <secondary>Testing an OMF File</secondary> 
    </indexterm> 
    <indexterm>
      <primary>ScrollKeeper</primary> 
      <secondary>Testing an OMF File</secondary> 
    </indexterm> 
    <para>
      Once you've written an OMF file, you should test it to make sure that
      it works.  To test an OMF file:
      <orderedlist>
        <listitem>
          <para>
            Make sure you have ScrollKeeper installed.
            You can always get it from <ulink type="http"
            url="http://sourceforge.net/projects/scrollkeeper">
            http://sourceforge.net/projects/scrollkeeper</ulink>. 
            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.
          </para>
        </listitem>
        <listitem>
          <para>
            Next you should make sure the url specified in the identifier element
            is accurate and points to a valid document.
          </para>
        </listitem>
        <listitem>
          <para>
            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 <command>scrollkeeper-install</command>.  For example: 
            <command>scrollkeeper-install -v -p <replaceable>testomf_db_dir</replaceable> 
            <replaceable>testomf.omf</replaceable></command>
            This will read the OMF file called <filename>testomf.omf</filename> and
            create a new ScrollKeeper catalog in the directory <filename 
            class="directory">testomf_db_dir</filename>. 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.
          </para>
        </listitem>
        <listitem>
          <para>
            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:
            <orderedlist>
              <listitem>
                <para>
                  <filename>testomf_db_dir/scrollkeeper_docs</filename> 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.
               </para>
             </listitem>
             <listitem>
               <para>
                 <filename>testomf_db_dir/TOC/0</filename> 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.
               </para>
             </listitem>
             <listitem>
               <para>
                 <filename>testomf_db_dir/index/0</filename> 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.
               </para>
             </listitem>
             <listitem>
               <para>
                 <filename>testomf_db_dir/index/<replaceable>locale</replaceable>/scrollkeeper_cl.xml</filename> 
                 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.
               </para>
             </listitem>
           </orderedlist>
         </para>
       </listitem>
       <listitem>
          <para>
             Now you are finished and can delete the temporary catalog 
            <filename class="directory">testomf_db_dir</filename>.
          </para>
        </listitem>
      </orderedlist>
    </para>
    <para>
      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: <programlisting>
      xmllint --noout --valid foo-C.omf</programlisting>  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.
    </para>
  </sect1>

<!-- =========== USING YOUR OMF FILE ============================== -->
  <sect1 id="skomf-using"> 
    <title>Using Your OMF File</title> 
    <para>
      Once you have completed and tested your OMF file, you are ready to
      use it.
    </para>
    <sect2 id="skomf-packaging"> 
      <title>Packaging Your OMF File</title> 
      <para>
        If you are packaging the OMF file with documentation in a
        package, see the examples and documentation in the package 
        scrollkeeper-example1, available from <ulink type="http"
        url="http://sourceforge.net/projects/scrollkeeper">
        http://sourceforge.net/projects/scrollkeeper</ulink>. 
      </para>
    </sect2>
    <sect2 id="skomf-registering"> 
      <title>Registering Your OMF File Locally</title> 
      <indexterm>
        <primary>OMF</primary> 
        <secondary>Registering Locally</secondary> 
      </indexterm> 
      <indexterm>
        <primary>ScrollKeeper</primary> 
        <secondary>Registering an OMF File Locally</secondary> 
      </indexterm> 
      <para>
        If you wish to register the OMF file and document in your local ScrollKeeper
        catalog, use <command>scrollkeeper-install</command> or 
        <command>scrollkeeper-update</command>.  A typical system-wide
        installation involves copying the OMF file into one of the
        directories specified by OMF_DIR in 
        <filename>/etc/scrollkeeper.conf</filename>, or a subdirectory
        of any of these directories.  Running <command>scrollkeeper-update</command>
        as root will update the catalog with any new or updated OMF files in
        these directories.  Conversely, if any OMF files were removed since the
        last <command>scrollkeeper-update</command>, their entries in the catalog
        will be removed.  Logs of the actions and any warnings or errors are
        written to <filename>/var/log/scrollkeeper.log</filename>.  You should
        now be able to view the updated catalog using any <ulink type="http"
        url="http://scrollkeeper.sourceforge.net/browsers.shtml">
        ScrollKeeper-compliant documentation browser</ulink>.  Note that you may
        need to restart some help browsers to see the changes.
      </para>
    </sect2>
  </sect1>

<!-- =========== Other Resources ============================== -->
  <sect1 id="skomf-otherresources"> 
    <title>Other Resources</title> 
    <indexterm>
      <primary>OMF</primary> 
      <secondary>Resources</secondary> 
    </indexterm> 
    <indexterm>
      <primary>ScrollKeeper</primary> 
      <secondary>OMF Resources</secondary> 
    </indexterm> 
    <para>
     For more information on ScrollKeeper and the OMF:
      <itemizedlist>
        <listitem>
          <para>
            <ulink type="http" url="http://www.ibiblio.org/osrt/omf/">
            OMF web pages</ulink>.  The OMF web pages contain the latest
            version of the official OMF scheme.
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink type="http" url="http://scrollkeeper.sourceforge.net">
            ScrollKeeper web pages</ulink>.  The ScrollKeeper web pages
            contain all the latest news, releases, and documentation about
            ScrollKeeper.
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink type="http" url="http://www.xml.com/pub/a/2001/11/28/scrollkeeper.html">
            "ScrollKeeper: Open Source Document Management"</ulink>.
            This article on xml.com gives a nice overview of ScrollKeeper
            and presents an interesting perspective on its place in
            Unix/Linux environments.
          </para>
        </listitem>
        <listitem>
         <para>
           db2omf.  db2omf extracts OMF metadata from DocBook documents.  It can
           be obtained from the <ulink type="http" 
           url="http://tldp.org/downloads/">LDP (Linux Documentation 
           Project)</ulink>.
         </para>
        </listitem>
      </itemizedlist>
    </para>
  </sect1>

</article>
