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.
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 Makefile.am 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:
%post
if which scrollkeeper-update>/dev/null 2>&1; then scrollkeeper-update -q -o %{_datadir}/omf/scrollkeeper-example2; fi
%postun
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.
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.
dnl ==================================== dnl = Begin tests for scrollkeeper dnl ==================================== AC_PATH_PROG(SK_CONFIG,scrollkeeper-config,no) if test x$SK_CONFIG = xno; then AC_MSG_ERROR(Couldn't find scrollkeeper-config. Please install the scrollkeeper package: http://scrollkeeper.sourceforge.net) fi dnl ==================================== dnl = End tests for scrollkeeper dnl ====================================You should also declare SCROLLKEEPER_BUILD_REQUIRED since RPM users will need this variable:
SCROLLKEEPER_BUILD_REQUIRED=0.3.5 AC_SUBST(SCROLLKEEPER_BUILD_REQUIRED)You will also need to add doc/Makefile to AC_OUTPUT, and similar entries for each subdirectory you create. For example:
AC_OUTPUT( scrollkeeper-example2.spec doc/Makefile doc/scrollkeeper-example2-manual/Makefile doc/scrollkeeper-example2-manual/C/Makefile Makefile)You will need to add an entry in AC_OUTPUT for each Makefile.am which you create below.
Add COPYING-DOCS Create COPYING-DOCS in the toplevel directory. This file should contain the license of your documentation.
Modify Makefile.am Put COPYING-DOCS into EXTRA_DIST and doc into SUBDIRS.
EXTRA_DIST= xmldocs.make omf.makeso that these files are included in tarballs of the package.
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
BuildRequires: scrollkeeper >= @SCROLLKEEPER_BUILD_REQUIRED@and
%post
if which scrollkeeper-update>/dev/null 2>&1; then scrollkeeper-update -q -o %{_datadir}/omf/scrollkeeper-example2; fi
%postun
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:
%{_datadir}/omf/scrollkeeper-example2
%{_datadir}/scrollkeeper-example2
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.)