install-docs
from the
postinst
script.
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 (.).
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 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.)
.
Then, it should call install-docs
from its postinst script
like this
if command -v install-docs >/dev/null 2>&1; then install-docs -i /usr/share/doc-base/<document-id> fiand from the prerm script like this
if command -v install-docs >/dev/null 2>&1; then install-docs -r <document-id> 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.