[ 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 Using
install-docs
, 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: 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
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 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.
Short paragraph giving an overview of the document; optional but recommended field.
Section where the document belongs; this should follow the sections outlined in
The
Debian Menu sub-policy
. 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.
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
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.
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
schwarz@debian.org
aph@debian.org
robert@debian.org