Chapter 2. The packages interface

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: Debian

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
      

If the doc-base package provided necessary files in other formats, it would be possible to add more sections at the end of the control file:

Format: PDF
Files: /usr/share/doc-base/doc-base.pdf

Format: PostScript
Files: /usr/share/doc-base/doc-base.ps.gz

Format: DVI
Files: /usr/share/doc-base/doc-base.dvi.gz

Format: Info
Index: /usr/share/info/doc-base.info.gz
Files: /usr/share/info/doc-base.info*.gz
      

As you can see from the above 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:

The section field holds a slash-separated list of hierarchical section components. The hierarchy is mostly based on the sections outlined in chapter 2.1 of the Debian Menu Policy; however the top-level Applications component was removed and a few doc-base-specific sections were added.

The full section list is presented below.

Since version 0.8.7 it is possible to provide documents with the same document-id by more than one binary package. All such documents will be merged together and the merged document will be generated in the /var/lib/doc-base/documents/document-id file. This feature can be useful in cases when the same documentation, but in different formats, is provided by two binary packages.

For example the foo-text package could install the /usr/share/doc-base/foo-text file with the following contents:

Document: foo
Title: This is foo
Author: John Foo <foo@foo.net>
Abstract: Description of foo
Section: Text

Format: text
Files: /usr/share/foo-text/foo.txt.gz
      

and the foo-html package could install the following /usr/share/doc-base/foo-html file:

Document: foo
Title: This is foo
Author: John Foo <foo@foo.net>
Abstract: Description of foo
Section: Text

Format: HTML
Index: /usr/share/foo-html/index.html
Files: /usr/share/foo-html/*.html
      

When both packages are installed, install-docs will merge the contents of the two files into /var/lib/doc-base/documents/foo:

Document: foo
Title: This is foo
Author: John Foo <foo@foo.net>
Abstract: Description of foo
Section: Text

Format: HTML
Index: /usr/share/foo-html/index.html
Files: /usr/share/foo-html/*.html

Format: text
Files: /usr/share/foo-text/foo.txt.gz
      

Version 0.8.7 and further allow a user to register local documentation. In order to do this local administrators need to create their own control file (see Section 2.3, “Control Files”, place it in the /etc/doc-base/documents directory, and then register it with

install-docs -i /etc/doc-base/documents/<document-id>
      

Before removing the file, it should be de-registered with

install-docs -r /etc/doc-base/documents/<document-id>
      

Since version 0.8.12

install-docs --install-changed
      

may be used instead of the two above commands.

doc-base 0.8.11 and greater use the dpkg triggers feature to register and de-register the documentation. There is no longer a need to call install-docs from maintainer scripts.