The mysteries of doc-base

If you have packaged enough Debian packages, and if you are dutifully checking your work with lintian, then sooner or later you will hit errors like:

The package ships a .html or .pdf file under /usr/share/doc/, which are usually documentation, but it does not register anything in doc-base. (Files under an examples directory are excluded.)

Refer to Debian Policy Manual section 9.10 (Registering Documents using doc-base) for details.

Severity: wishlist, Certainty: possible

And indeed recently I have worked on the Debian packaging for a number of packages that involved doc-base: mod_perl2, MaraDNS and another package that is in progress. So I thought I would try and review what it is for.

What is doc-base?

According to its description, doc-base …

… contains utilities to manage documentation installed on a Debian system. It generates a database of document metadata, which other packages such as dwww, dhelp, doc-central, and rarian-compat can use to provide a catalog of available documentation.

In other words doc-base is a sort of documentation clearing house. Packages tell it what documentation they have and doc-base files the information in a systematic manner. In turn documentation applications can index the data and present it to the user however they like. The document formats supported are HTML, text, PDF, PostScript, info, DVI, Debian doc SGML.

Frustratingly POD is not supported. Previous versions of the mod_perl documentation, provided a lot of POD formatted documentation but with no structure. With 2.05-1 I put a lot of effort into using the Pod::Html to change the POD files to HTML with wherever possible working links and as required by doc-base an index of all of the generated HTML files. I can see some potential improvements but it is definitely more useable now.

How does one actually search doc-base?

The only method of searching doc-base provided by doc-base itself is the -s option of install-docs.

/usr/sbin/install-docs -s libpache2-mod-perl2-doc

However this is clearly not meant for the end user. You need to use one of the separate front ends. This is a good thing. It is a clear example of separation of concerns — concentrating on what you can do well and communicating well with other components that do what you do not do.

Going by the package name alone, one might have high hopes for doc-central. However the developer has not been active since 2005, I had to tweak the apache configuration to get it to work at all. Even then there is no transparent handling of compressed documentation, which makes it essentially unusable on Debian systems.

So right now I am using dwww. It combines not just the documentation indexed by doc-base, but man pages, info documents (even if not directly registered with doc-base), the documentation below the /usr/share/doc/ directory and allows both hierarchical browsing and a search interface. If you want to customize the look and feel the dwww(7) man page should be your starting point. It requires a CGI capable web server.

How do I register documents with doc-base?

Registering documents with doc-base is quite straightforward. Your package must contain a debian/doc-base or debian/${package}.doc-base file. The format is described in /usr/share/doc/doc-base/doc-base.html/ch-inteface.html and might look like:

Document: libapache2-mod-perl2-doc
Title: Apache2 mod_perl2 documentation
Author: Nicholas Bamber
Abstract:
 Mod_perl allows the use of Perl for just about anything
 Apache-related, including <Perl> sections in the config
 files and the famous Apache::Registry module for caching
 compiled scripts.
Section: Web Development

Format: Text
Files:
 /usr/share/doc/libapache2-mod-perl2-doc/todo

Format: HTML
Index: /usr/share/doc/libapache2-mod-perl2-doc/index.html
Files: /usr/share/doc/libapache2-mod-perl2-doc/docs

That is essentially it. The only difficult bit is that some file types (for example HTML) require an index file; so sometimes one has to generate one.

How does doc-base actually work?

It used to be the case that you had to call install-docs from inside your postinst and postrm scripts. Since the advent of dpkg triggers this is not correct, and in that context it will do nothing. The actual sequence is as follows:

• During the package building process, the dh_installdocs arranges for the doc-base control file to be installed to /usr/share/doc-base/.
• The doc-base package has registered a trigger on the file /usr/share/doc-base directory. So when dpkg installs a file to that directory, the postinst script of the doc-base package will be called with "triggered" as its first argument.
• The doc-base postinst script then calls install-docs with the appopriate arguments.