[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ next ]


Debian doc-base Manual
Chapter 2 - The packages interface



2.1 Introduction

Each Debian package that installs online manuals (in any format) should register its manuals to doc-base. This is done by installing a doc-base control file (see Control Files, Section 2.3) and calling install-docs from the postinst script (see Registering Documents Using install-docs, Section 2.4).


2.2 Document IDs

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).


2.3 Control Files

For each piece online documentation, doc-base needs a control file that describes the documentation and the documentation file formats that are provided initially.


2.3.1 Example

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

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

2.3.2 Syntax of the control file

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:


2.3.2.1 The main section

The first section of the control file describes the document. The following fields are available:

Document

Document ID, required field; should be the first field.

Title

Title of the document; required field.

Abstract

Short paragraph giving an overview of the document; optional but recommended field.

Section

Section where the document belongs; this should follow the sections outlined in The Debian Menu sub-policy. Required field.


2.3.2.2 Format sections

The next sections describe the different formats for the provided document which is described in the first section. The following fields are available:

Format

Format for the document. Required field. The following formats are recognised:

The values of this field are case-insensitive (e.g. both Text and text are valid).

Index

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.

This 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.

Files

Space separated list of filenames or POSIX shell globs (i.e. *, ?, and [] meta-characters) representing the files which constitute the documentation in this format. Required field.

There must be at least one such a section. If there are more, each of them must register files in different formats (e.g. having two Format: HTML sections in one control file is not allowed).

Except for the Info format the files referred in both Index and Files fields should be placed somewhere under the /usr/share/doc hierarchy. If for some reason it's not possible, then the registering package should provide a symbolic link pointing from the above hierarchy to the real files and register its documentation through the link, allowing doc-base, dhelp, or dwww packages to actually handle the documentation. Of course, files in the Info format should be located in the /usr/share/info directory.


2.4 Registering Documents Using install-docs

In order to register a piece of online documentation to doc-base, the package must install the control file (see Control Files, Section 2.3) 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 /usr/share/doc-base/<document-id>
         fi
       fi

With that, doc-base will automatically register the online manuals to dww, dhelp, and scrollkeeper 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

2.4.1 doc-base 0.8.4 features and incompatibilities

The semantics of the remove call has been changed in version 0.8.4: install-docs -r require the full path of control file to be passed. Previous syntax (i.e. passing only document-id) is still supported for backward compatibility. Older versions of install-docs ignore the new syntax (only issue a warning, but don't fail).

With 0.8.4 and later is possible to install (and remove) multiple documents in one call, like

     install-docs -i /usr/share/doc-base/<document-id_1> \
                     /usr/share/doc-base/<document-id_2> \
                     /usr/share/doc-base/<document-id_3>

or even

     cat << EOF | install-docs -i -
     /usr/share/doc-base/<document-id_1>
     /usr/share/doc-base/<document-id_2>
     /usr/share/doc-base/<document-id_3>
     EOF

However older versions will fail on such a syntax, so it's necessary to add proper Conflicts or Depends line if you plan to use the feature in your package.


2.5 Checking Syntax of Control Files

With the new --check (-c) option of install-docs it is possible to check the control file:

     $ install-docs --check /usr/share/doc-base/doc-base 
     /usr/share/doc-base/doc-base: No problems found
     $ install-docs -c /usr/share/doc-base/xlogmaster
     Error in `/usr/share/doc-base/xlogmaster', line 15: `Index' value missing for format info
     /usr/share/doc-base/xlogmaster: Fatal error found, the file won't be registered
     $ install-docs -c /usr/share/doc-base/MC-FAQ /usr/share/doc-base/gnu-privacy-handbook
     /usr/share/doc-base/MC-FAQ: 1 warning(s) or non-fatal error(s) found
     /usr/share/doc-base/gnu-privacy-handbook: 1 warning(s) or non-fatal error(s) found

More details about the warnings and non-fatal errors can be found using the --verbose (-v) option:

     $ install-docs -v -c /usr/share/doc-base/MC-FAQ /usr/share/doc-base/gnu-privacy-handbook
     Warning in `/usr/share/doc-base/MC-FAQ', line 1: invalid value of `Document' field
     /usr/share/doc-base/MC-FAQ: 1 warning(s) or non-fatal error(s) found
     Warning in `/usr/share/doc-base/gnu-privacy-handbook', line 12: file `/usr/share/doc/gnupg-doc/GNU_Privacy_Handbook/html/book1.html' does not exist
     /usr/share/doc-base/gnu-privacy-handbook: 1 warning(s) or non-fatal error(s) found

With the --rootdir option is possible to check non-installed packages:

     $ dpkg-deb -x autoclass_3.3.4-6_i386.deb AUTOCLASS_UNPACKED
     $ install-docs --rootdir AUTOCLASS_UNPACKED -vc AUTOCLASS_UNPACKED/usr/share/doc-base/*
     AUTOCLASS_UNPACKED/usr/share/doc-base/autoclass-results: No problems found
     AUTOCLASS_UNPACKED/usr/share/doc-base/autoclass-theory: No problems found

If the --rootdir option was omitted, install-docs would complain:

     Warning in `AUTOCLASS_UNPACKED/usr/share/doc-base/autoclass-results', line 20: file mask `/usr/share/doc/autoclass/kdd-95.pdf' does not match any files
     Warning in `AUTOCLASS_UNPACKED/usr/share/doc-base/autoclass-theory', line 20: file mask `/usr/share/doc/autoclass/tr-fia-90-12-7-01.pdf' does not match any files

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ next ]


Debian doc-base Manual

ver. 0.8.4, 06 May, 2007

Christian Schwarz schwarz@debian.org
Adam Di Carlo aph@debian.org
Robert Luberda robert@debian.org