[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ next ]
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. The field names are case-insensitive. 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. If the Abstract field value should contain lines displayed varbatim, the lines must begin with two spaces.
The first section of the control file describes the document. The following fields are available:
Document ID, required field; should be the first field.
Title of the document; required field.
Short paragraph giving an overview of the document; optional but recommended field.
Section where the document belongs; this should follow the sections outlined in The Debian Menu sub-policy.
The following sections describe the different formats for the provided document which is described in the first section. The following fields are available:
Format for the document. Required field. The following formats are recognized: "HTML", "Text", "PDF", "PostScript", "Info", "DVI", and "DebianDoc-SGML".
Index or top-level file for this document format. Only applies to document formats "HTML" and "Info", and required if the format is "HTML" or "Info".
Space separated list of filenames or shell globs representing the files which constitute the documentation in this format. Required field.
The `Index:' field has to contain the absolute file name of the main 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 ] || [ "$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
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ next ]
Debian doc-base
Manual
schwarz@debian.org
aph@debian.org