doc-base
Manual
Each Debian package that installs online manuals (any format) should register
its manuals to doc-base
. This is done by installing a
doc-base
control file and calling
install-docs
from the postinst
script.
Each document that is registered to doc-base
must have a 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
Legal characters for the document ID are lower case letters (a-z), digits (0-9), plus (+) or minus (-) signs, and dots (.) (the same characters allowed in package names).
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/share/doc/doc-base/doc-base.sgml.gz Format: text Files: /usr/share/doc/doc-base/doc-base.txt.gz Format: HTML Index: /usr/share/doc/doc-base/doc-base.html/index.html Files: /usr/share/doc/doc-base/doc-base.html/*.html
As you can see from this example, the syntax -- as is 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 simple to remember the basic ideas.
The syntax of the control file is simple: Empty lines separate sections (see below). Non-empty lines use a field-value syntax. Field values may be wrapped over several lines by making the first character of subsequent lines a space; if a multi-line value should contain an empty line, a single dot (.) must be placed in the second column. The field names are case-insensitive.
The first section of the control file describes the document. The following fields are available:
The following sections describe the different formats for the provided document which is described in the first section. The following fields are available:
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 the front page link when the document is registered.
install-docs
In order to register a piece of online documentation to doc-base
,
the package must 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 which 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 which 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
Debian doc-base
Manual
schwarz@debian.org
aph@debian.org