[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ next ]
doc-base Manual
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).
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).
For each piece online documentation, doc-base needs a control
file that describes the documentation and the documentation file formats
that are provided initially.
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 file consist of
exactly one main section providing base information about the registered manual (see The main section, Section 2.3.2.1 below);
one or more format sections (see Format sections, Section 2.3.2.2) 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.
The first section of the control file describes the document. The following fields are available:
Document ID, required field; should be the first field.
Title of the document; required field.
Author(s) of the document; optional field.
Short paragraph giving an overview of the document; optional but recommended field.
Section where the document belongs; see The section field, Section 2.3.3. Required field.
The next sections describe the different formats for the provided document which is described in the first section. The following fields are available:
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 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.
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.
The section field holds 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.
Documentation of tools to aid people with disabilities or for machines lacking usual input devices.
Anything relating to HAM radio.
Interactive database programs, collection managers, address books, bibliography tools, etc.
Documentation of Debian specific tools, policies, etc.
Documentation of editors, other than office word processors, for text-based information.
Educational and training softwares.
Software that allows you to run non-native software or more than one OS at a time.
Tools for file management, archiving, searching, CD/DVD burning, backup, etc.
Games and recreations. Entries should be placed in appropriate subsection.
Games that involve a lot of action and require fast reflexes.
Role playing and adventure games, interactive movies and stories, etc.
Tetris-like games involving falling blocks.
Games played on a board.
Games involving a deck of cards.
Tests of ingenuity and logic.
Simulations of the real world in all detail and complexity.
Games involving long-term strategic thinking.
Server browsers, configurators, editors, and other game-related tools that are not games themselves.
Amusements, eye-candy, entertaining demos, screen hacks (screen-savers), etc.
2D and 3D graphics manipulation software.
Documentation of programs that provide user documentation.
Books.
Frequently Asked Questions.
Various HOWTOs.
RFCs
Standards
Software that allows you to interface with mobile devices (phones, PDAs, etc.).
Network related software. This is a two-level section, do not put entries directly here.
Mail, USENET news, chat, instant messaging, IP telephony, video conferencing software, etc.
File transfer software such as download managers, FTP clients, P2P clients, etc.
Network monitoring software
Tools for remotely managing of computer
Web browsers, tools for offline browsing, etc.
Web feed (RSS, Atom, etc.) and podcast aggregators.
Office suites, word processors, spreadsheets, CRM, ERP, financial software, etc.
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:
Programming/C
Programming/C++
Programming/Java
Programming/OCaml
Programming/Perl
Programming/Python
Programming/Ruby
Timetable managers, group task trackers, bug tracking software, etc.
Documentation of scientific and engineering-related software. Please use appropriate subsection.
Astronomy-related software.
Biology-related software.
Chemistry-related software.
Software designed for processing, extracting, and presenting generic scientific data.
Circuit design tools, simulators and assemblers for microprocessors, etc
CAD, UML tools, diagram-drawing and other engineering-related software.
Geoscience-related software.
Mathematics-related software.
Medicine-related software.
Physics-related software.
Social sciences-related software.
Programs that affect the whole screen.
Tools for blanking the screen. Entries of screen hacks and configuration GUIs should go to other appropriate sections.
Tools for locking the screen.
Various shells to be used inside a terminal emulator.
Sound players, editors, and rippers/recorders.
System related software. Place entries in one of she subsections.
Administrative and system configuration utilities, also tools for personal user settings.
Tools for manipulating specific hardware, especially non-standard laptop hardware.
This section is reserved for language-env as a special case.
System information and monitoring tools, log viewers, etc.
Package managers and related tools.
Security, cryptography and privacy related software, antiviruses, tools to track and report bugs, etc.
Graphical terminal emulators.
Text oriented tools like dictionaries, OCR, translation, text analysis software, etc.
TV-in, TV-out, FM radio, teletext browsers, etc.
Software for typesetting text and graphics from structured input files like LaTeX or docbook sources, database exports etc.
Software for viewing images, documents and other (non-video) media.
Video players, editors, and rippers/recorders.
Software for web site editing, web programming, and site administration.
X window managers.
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 dwww, dhelp, and
scrollkeeper when the package is installed, and de-register the
manuals when the package is removed.
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
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.
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.
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
mailto:schwarz@debian.orgmailto:aph@debian.orgmailto:robert@debian.org