#51 scrollkeeper_manual FIXMEs should be fix
The scrollkeeper manual needs to be finished.
If it is useful, below is a little bit of DocBook I
wrote for Kevin Breit that I've since shared with one
other developer struggling to get omf/ScrollKeeper
working right. I'm happy to share it with others if
it's useful.
<sect1 id="jffor-developers">
<title>Installing with Scrollkeeper</title>
<para>For developers, setting up an application to
correctly install
<acronym>OMF</acronym>
documentation with
<application>Scrollkeeper</application> requires two
steps, one during the build
stage and one during the install stage.
</para>
<sect2 id="jfbuild">
<title>Building</title>
<para>
One problem faced by the developers of the
<acronym>OMF</acronym>/<application>Scrollkeeper</application> system is
that the <acronym>OMF</acronym> files requires the
<acronym>URL</acronym> pointing to the file's location,
but that will
not be known when the file is written.
</para>
<para>
This problem is solved with the
<application>scrollkeeper-preinstall</application>
script, which takes
the <acronym>OMF</acronym> from the package and modifies
it with the
documentation location specified at build time.
</para>
<para>
A typical makefile for this step will look like this,
taking three
parameters: the URL for the installed document, the original
<acronym>OMF</acronym> metadata file in
<acronym>XML</acronym>, and the name that the generated
<acronym>OMF</acronym> file should be written to.
<programlisting>
<![CDATA[
scrollkeeper-preinstall \
file:$(docdir)/foo-manual.sgml \
foo-manual-fr.omf \
$(omf-dir)/foo-manual-fr.omf
]]>
</programlisting>
It will create a modified version of the
<acronym>OMF</acronym> file,
containing the final URL where the file will be
installed. The modified
<acronym>OMF</acronym> file is then temporarily stored
in<varname>$(omf-dir)</varname>.
</para>
</sect2>
<sect2 id="jfinstall">
<title>Installing</title>
<para>
Installing the final <acronym>OMF</acronym> file and
updating the
Scrollkeeper database takes two steps.
</para>
<para>
First, the <command>make install</command> copies the
<acronym>OMF</acronym> file into the appropriate
location on the
machine, along with the document itself:
<programlisting>
<![CDATA[
install foo-manual.sgml $(docdir)
install $(omf-dir)/foo-manual-fr.omf $(pkgomfdir)
]]>
</programlisting>
Second, the <application>Scrollkeeper</application>
database needs to be
updated:
<programlisting>
<![CDATA[
-scrollkeeper-update -p $(SCROLLKEEPER_DB_DIR)
]]>
</programlisting>
<varname>$(SCROLLKEEPER_DB_DIR)</varname> is the
directory holding the
<application>Scrollkeeper</application> files, and is
based on
<varname>localstatedir</varname>.
<note>
<para>
More details on the installation procedures and the
philosophy behind
them is available on the Scrollkeeper web site: <ulink
url="http://scrollkeeper.sourceforge.net/data/scrollkeeper_0.2_specs.txt">ScrollKeeper
0.2 Specifications
</ulink>.
</para>
<para>
There also is a sample packaging example in GNOME cvs:
<filename>gnome-docu/gdp/gdp-example1/</filename>
</para>
</note>
</para>
</sect2>
</sect1>
Logged In: YES
user_id=65682
I need to check whether this is all still correct and
relevant. If so, one of us (jfleck or me) needs to update it
for the 0.3 releases and dump it into CVS.
Scrollkeeper definitely needs more documentation explaining
what on earth is going on in various places, so I do not
want to lose this.