Debian doc-base Manual

Christian Schwarz

   <schwarz@debian.org>

Adam Di Carlo

   <aph@debian.org>

Robert Luberda

   <robert@debian.org>

   ver. 0.11.1

   Copyright © 1998, Christian Schwarz

   Copyright © 1999 - 2002, Adam Di Carlo

   Copyright © 2006 - 2018, Robert Luberda

   This manual is free software; you may redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the
   Free Software Foundation; either version 2, or (at your option) any
   later version.

   This is distributed in the hope that it will be useful, but without any
   warranty; without even the implied warranty of merchantability or
   fitness for a particular purpose. See the GNU General Public License
   for more details.

   A copy of the GNU General Public License is available as
   /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or
   on the World Wide Web at the GNU website. You can also obtain it by
   writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth
   Floor, Boston, MA 02110-1301 USA.

   25 January 2021

   Abstract

   This manual describes what doc-base is and how it can be used to manage
   online manuals on Debian systems.
     __________________________________________________________________

   Table of Contents

   1. About doc-base
   2. The packages interface

        2.1. Introduction
        2.2. Document IDs
        2.3. Control Files

              2.3.1. Example
              2.3.2. Syntax of the control file

                    2.3.2.1. The main section
                    2.3.2.2. Format sections

              2.3.3. The section field

        2.4. Registering Documents With doc-base
        2.5. doc-base 0.8.x features and incompatibilities

              2.5.1. Splitting control files over multiple binary packages
              2.5.2. Registering local documents
              2.5.3. dpkg triggers

        2.6. Checking Syntax of Control Files

   3. Getting information about installed documents
   4. TODO List

        4.1. Roadmap for 0.9.* releases
        4.2. Old TODO entries

Chapter 1. About doc-base

   Some time ago, there was a big discussion on the Debian mailing lists
   about the preferred documentation format in Debian. The discussion
   showed clearly that people have very different opinions on that topic
   and thus, we'll have to implement a flexible solution.

   The doc-base package tries to implement such a flexible solution: every
   Debian package that provides online documentation (other than manual
   pages) will register these documents to doc-base via the install-docs
   script (see Section 2.4, "Registering Documents With doc-base") at
   installation time and de-register the manuals again when the package is
   removed.

   Since all manuals will eventually be registered, doc-base can also be
   used to solve another outstanding problem: Debian currently has four
   different online documentation systems, doc-central, dwww, dochelp, and
   dhelp. Each system has advantages and disadvantages; thus doc-base
   supports all of them. The system administrator can choose which
   implementation he/she prefers.

Chapter 2. The packages interface

   Table of Contents

   2.1. Introduction
   2.2. Document IDs
   2.3. Control Files

        2.3.1. Example
        2.3.2. Syntax of the control file

              2.3.2.1. The main section
              2.3.2.2. Format sections

        2.3.3. The section field

   2.4. Registering Documents With doc-base
   2.5. doc-base 0.8.x features and incompatibilities

        2.5.1. Splitting control files over multiple binary packages
        2.5.2. Registering local documents
        2.5.3. dpkg triggers

   2.6. Checking Syntax of Control Files

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 Section 2.3, "Control Files") and calling
   install-docs from the postinst script (see Section 2.4, "Registering
   Documents With doc-base").

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 of 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:
     * The file consist of
          + exactly one main section providing base information about the
            registered manual (see Section 2.3.2.1, "The main section"
            below);
          + one or more format sections (see Section 2.3.2.2, "Format
            sections") containing pointers to the registered documentation
            files.
     * Successive sections must be separated with empty lines.
     * Non-empty lines use a `field-name: value' syntax.
     * The field names are case-insensitive.
     * The field values are case-sensitive (except for the Format field).
     * Field values may be wrapped over several lines by making the first
       character of subsequent lines a space.
          + If a multi-line value should contain an empty line, a single
            dot (.) must be placed in the second column.
          + If the Abstract field value should contain lines displayed
            verbatim, the lines must begin with two spaces.
     * The file should be encoded in UTF-8.

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 Section 2.3.3, "The
          section field". 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:

          + HTML,
          + Text,
          + PDF,
          + PostScript,
          + Info,
          + DVI,
          + and DebianDoc-SGML.

          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 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 to 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 the 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 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.

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

   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 the
          appropriate subsection.

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

        Games/Adventure
                Role playing and adventure games, interactive movies and
                stories, etc.

        Games/Blocks
                Tetris-like games involving falling blocks.

        Games/Board
                Games played on a board.

        Games/Card
                Games involving a deck of cards.

        Games/Puzzles
                Tests of ingenuity and logic.

        Games/Simulation
                Simulations of the real world in all detail and
                complexity.

        Games/Strategy
                Games involving long-term strategic thinking.

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

        Games/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.

        Help/Books
                Books.

        Help/FAQ
                Frequently Asked Questions.

        Help/HOWTO
                Various HOWTOs.

        Help/RFC
                RFCs

        Help/Standards
                Standards

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

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

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

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

        Network/Monitoring
                Network monitoring software.

        Network/Remote Access
                Tools for remotely managing a computer.

        Network/Web Browsing
                Web browsers, tools for offline browsing, etc.

        Network/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 the subsection named like the language, for
          example:

          + Programming/C
          + Programming/C++
          + Programming/Java
          + Programming/OCaml
          + Programming/Perl
          + Programming/Python
          + Programming/Ruby

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

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

        Science/Astronomy
                Astronomy-related software.

        Science/Biology
                Biology-related software.

        Science/Chemistry
                Chemistry-related software.

        Science/Data Analysis
                Software designed for processing, extracting, and
                presenting generic scientific data.

        Science/Electronics
                Circuit design tools, simulators and assemblers for
                microprocessors, etc.

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

        Science/Geoscience
                Geoscience-related software.

        Science/Mathematics
                Mathematics-related software.

        Science/Medicine
                Medicine-related software.

        Science/Physics
                Physics-related software.

        Science/Social
                Social sciences-related software.

   Screen
          Programs that affect the whole screen.

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

        Screen/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 the
          subsections.

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

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

        System/Language Environment
                This section is reserved for language-env as a special
                case.

        System/Monitoring
                System information and monitoring tools, log viewers, etc.

        System/Package Management
                Package managers and related tools.

        System/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 install the control file (see Section 2.3,
   "Control Files") 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 the
   /var/lib/doc-base/documents/<document-id> file and register the online
   manuals to dwww, and dhelp, 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 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

2.5.2. Registering local documents

   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.

2.5.3. dpkg triggers

   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.

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 fo
rmat 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-han
dbook
/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) fou
nd

   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' fie
ld
/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) fou
nd

   With the --rootdir option it 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: f
ile 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: fi
le mask `/usr/share/doc/autoclass/tr-fia-90-12-7-01.pdf' does not match any file
s

Chapter 3. Getting information about installed documents

   If you want to get information about the status of an installed manual,
   you can use the `-s' or `--status' option of install-docs followed by
   the document id:
$ install-docs -s foo
---document-information---
Document: foo
Abstract: This manual is about foos, bars, and Debian.
Author: Wile E. Coyote
Section: Debian
Title: Debian Foo's Manual

---format-description---
Format: debiandoc-sgml
Files: /usr/share/doc/foo/sgml/foo.sgml.gz

---format-description---
Format: html
Files: /usr/share/doc/foo/html-sgml/*.html
Index: /usr/share/doc/foo/html-sgml/index.html

---status-information---
Control-Files: /usr/share/doc-base/foo (changed: Tue Apr  8 23:09:24 2008)

   doc-base always creates a /var/lib/doc-base/documents/<document-id>
   file when installing a document.

Chapter 4. TODO List

   Table of Contents

   4.1. Roadmap for 0.9.* releases
   4.2. Old TODO entries

4.1. Roadmap for 0.9.* releases

     * Internationalisation and po-debconf support. Unfortunately this
       would require merging Abstract and Title fields into one
       Description field. See Bug#171363, Bug#171375, and Bug#171378.
     * Introduce some new fields, like Package (Bug#71955), or SortSkip
       (Bug#187590).
     * Possibly allow documents to appear in multiple sections; see Steve
       M. Robbins' mail.
     * Possibly index documentation with swish++ that could be used by
       frontends like dhelp or dwww.

4.2. Old TODO entries

     * Policy: document the doc-base document registration file format
       separately (or SUBDOC it) as a proposed Debian documentation system
       policy.
     * Policy: define a first-cut standard as the document hierarchy.
     * Documentation update: show clean and minimal use of install-docs
       from a maintainer script.
     * It is extremely difficult to deal coherently with a misnamed
       control file, or a mismatch between a control file and the document
       field. This hit me in the transition between doc-base 0.4 to 0.5
       (in 0.4 I had added, in a file install-docs-man, a document ID
       named install-doc-man). Something needs to be done about that.
     * Automated format conversion, including user preferences. (For
       example, convert Texinfo source to GNU info or PostScript,
       optionally compress or remove HTML manuals which are also available
       in GNU info format, etc. etc.)
