[ 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 With doc-base, 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: 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

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.

Author

Author(s) of the document; optional field.

Abstract

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

Section

Section where the document belongs; see The section field, Section 2.3.3. 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.3.3 The section field

The section field hold a slash-separated list of hierarchical sections 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.

Accessibility

Documentation of tools to aid people with disabilities or for machines lacking usual input devices.

Amateur Radio

Anything relating to HAM radio.

Data Management

Interactive database programs, collection managers, address books, bibliography tools, etc.

Debian

Documentation of Debian specific tools, policies, etc.

Editors

Documentation of editors, other than office word processors, for text-based information.

Education

Educational and training softwares.

Emulators

Software that allows you to run non-native software or more than one OS at a time.

File Management

Tools for file management, archiving, searching, CD/DVD burning, backup, etc.

Games

Games and recreations. Entries should be placed in appropriate subsection.

Action

Games that involve a lot of action and require fast reflexes.

Adventure

Role playing and adventure games, interactive movies and stories, etc.

Blocks

Tetris-like games involving falling blocks.

Board

Games played on a board.

Card

Games involving a deck of cards.

Puzzles

Tests of ingenuity and logic.

Simulation

Simulations of the real world in all detail and complexity.

Strategy

Games involving long-term strategic thinking.

Tools

Server browsers, configurators, editors, and other game-related tools that are not games themselves.

Toys

Amusements, eye-candy, entertaining demos, screen hacks (screen-savers), etc.

Graphics

2D and 3D graphics manipulation software.

Help

Documentation of programs that provide user documentation.

Books

Books.

FAQ

Frequently Asked Questions.

HOWTO

Various HOWTOs.

RFC

RFCs

Standards

Standards

Mobile Devices

Software that allows you to interface with mobile devices (phones, PDAs, etc.).

Network

Network related software. This is a three-level section, do not put entries directly here.

Communication

Mail, USENET news, chat, instant messaging, IP telephony, video conferencing software, etc.

File Transfer

File transfer software such as download managers, FTP clients, P2P clients, etc.

Monitoring

Network monitoring software

Web Browsing

Web browsers, tools for offline browsing, etc.

Web News

Web feed (RSS, Atom, etc.) and podcast aggregators.

Office

Office suites, word processors, spreadsheets, CRM, ERP, financial software, etc.

Programming

IDEs, debuggers, compilers, APIs, libraries, programming languages. Documentation related to only one specific language should be put in subsection named like the language, for example:

Project Management

Timetable managers, group task trackers, bug tracking software, etc.

Science

Documentation of scientific and engineering-related software. Please use appropriate subsection.

Astronomy

Astronomy-related software.

Biology

Biology-related software.

Chemistry

Chemistry-related software.

Data Analysis

Software designed for processing, extracting, and presenting generic scientific data.

Electronics

Circuit design tools, simulators and assemblers for microprocessors, etc

Engineering

CAD, UML tools, diagram-drawing and other engineering-related software.

Geoscience

Geoscience-related software.

Mathematics

Mathematics-related software.

Medicine

Medicine-related software.

Physics

Physics-related software.

Social

Social sciences-related software.

Screen

Programs that affect the whole screen.

Saving

Tools for blanking the screen. Entries of screen hacks and configuration GUIs should go to other appropriate sections.

Locking

Tools for locking the screen.

Shells

Various shells to be used inside a terminal emulator.

Sound

Sound players, editors, and rippers/recorders.

System

System related software. Place entries in one of she subsections.

Administration

Administrative and system configuration utilities, also tools for personal user settings.

Hardware

Tools for manipulating specific hardware, especially non-standard laptop hardware.

Language Environment

This section is reserved for language-env as a special case.

Monitoring

System information and monitoring tools, log viewers, etc.

Package Management

Package managers and related tools.

Security

Security, cryptography and privacy related software, antiviruses, tools to track and report bugs, etc.

Terminal Emulators

Graphical terminal emulators.

Text

Text oriented tools like dictionaries, OCR, translation, text analysis software, etc.

TV and Radio

TV-in, TV-out, FM radio, teletext browsers, etc.

Typesetting

Software for typesetting text and graphics from structured input files like LaTeX or docbook sources, database exports etc.

Viewers

Software for viewing images, documents and other (non-video) media.

Video

Video players, editors, and rippers/recorders.

Web Development

Software for web site editing, web programming, and site administration.

Window Managers

X window managers.


2.4 Registering Documents With doc-base

In order to register a piece of online documentation to doc-base, all the package needs to do is installing the control file (see Control Files, Section 2.3) as file /usr/share/doc-base/document-id.

Further processing of the control file is handled by a dpkg trigger (cf. /usr/share/doc/dpkg/triggers.txt.gz) provided by doc-base. The trigger will call install-docs to generate /var/lib/doc-base/documents/<document-id> file and register the online manuals to dww, dhelp, and scrollkeeper when the package is installed, and de-register the manuals when the package is removed.


2.5 doc-base 0.8.x features and incompatibilities


2.5.1 Splitting control files over multiple binary packages

Since version 0.8.7 is it possible to provide documents with the same document-id by more than one binary package. All such documents with be merged together and the merged document will be generated in /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 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

2.5.2 Registering local documents

Version 0.8.7 and furthers allow user to register local documentations. In order to do this local administrators need to create their own control file (see Control Files, Section 2.3, 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.


2.5.3 dpkg triggers

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


2.6 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.9.5, 15 October, 2009

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