Debian doc-base Manual
Chapter 2 - The packages interface
2.1 Introduction
Each Debian package that installs online manuals (any format) should register
its manuals to doc-base. This is done by installing a
doc-basecontrol file and calling
install-docs from the postinst script.
2.2 Document ids
Each piece of online documentation that is registered to doc-base
must have an unique document id.
The document id is usually taken from the document's title or from the package
name. Here are a few examples:
DOCID Title
---------------------- ----------------------------
debian-policy Debian Policy Manual
developers-reference Debian Developers Reference
doc-base Debian doc-base Manual
emacs-manual GNU Emacs Manual
Just as package names, the document id may only consist lower case letters
(a-z), digits (0-9), plus (+) or minus (-) signs, and dots (.).
2.3 Control files
For each piece online documentation, doc-base needs a control
file that describes the documentation and the documentation file formats
that are provided initially.
Here is an example of a control file:
Document: doc-base
Title: Debian doc-base Manual
Author: Christian Schwarz
Abstract: This manual describes what doc-base is
and how it can be used to
manage online manuals on Debian systems.
Section: Apps/Programming
Format: debiandoc-sgml
Files: /usr/doc/doc-base/doc-base.sgml.gz
Format: text
Files: /usr/doc/doc-base/doc-base.text.gz
Format: HTML
Index: /usr/doc/doc-base/doc-base.html/index.html
Files: /usr/doc/doc-base/doc-base.html/*.html
As you can see from this example, the syntax--just as the whole design of
doc-base--is heavily influenced by dpkg. This is important since
every maintainer will have to work with doc-base and thus, it
should be simply to remember the basic ideas.
The syntax of the control file is simple: Empty lines seperate sections (see
below). The other line use a field-value syntax. Field values may be wrapped
over several lines if the first character of subsequent lines is a space; if
the value should contain an empty line a single dot (.) has to be placed in the
second column. The field names are case-insensitive.
The first section of the control file describes the document, starting with the
document id (the `Document:' field), the title, etc. This information will be
used when the manual is registered to the online menu systems
(dhelp, dwww, etc.).
The following sections describe the different formats which are provided by the
package. This information will be needed when the format-conversion feature is
implemented. (Note, that these fields are likely to be changed as soon as I
start with the implementation.)
For now, only the format `HTML' is recognized. The `Index:' field has to
contain the absolute file name of the title page of the document. (This file
will be specified as front page link when the document is registered to
dwww or dhelp.)
2.4 Registering documents using install-docs
In order to register a piece of online documentation to doc-base,
the package has to install the control file (see above) as file
/usr/share/doc-base/document-id.
Then, it should call install-docs from its postinst
script:
if [ "$1" = configure ]; then
if command -v install-docs >/dev/null 2>&1; then
install-docs -i /usr/share/doc-base/<document-id>
fi
fi
and from the prerm script as well:
if [ "$1" = remove -o "$1" = upgrade ]; then
if command -v install-docs >/dev/null 2>&1; then
install-docs -r <document-id>
fi
fi
With that, doc-base will automatically register the online manuals
to dwww and dhelp when the package is installed, and
de-register the manuals when the package is removed.
Note that the call to remove the registered documentation from the
prerm maintainer script is necessary for cases such as when the
documentation directory changes and you want to avoid messages such as
dpkg: warning - unable to delete old file `directory': Directory not empty