Debian `doc-base' Manual ------------------------ Christian Schwarz Adam Di Carlo ver. 0.7.11-0.woody1, 14 May, 2005 ------------------------------------------------------------------------------- Abstract -------- This manual describes what `doc-base' is and how it can be used to manage online manuals on Debian systems. Copyright Notice ---------------- copyright (C)1998, Christian Schwarz copyright (C)1999 -- 2001, Adam Di Carlo 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 (http://www.gnu.org/copyleft/gpl.html). You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ------------------------------------------------------------------------------- Contents -------- 1. About `doc-base' 2. The packages interface 2.1. Introduction 2.2. Document ids 2.3. Control files 2.4. Registering documents using `install-docs' 3. Getting information about installed documents 4. TODO List ------------------------------------------------------------------------------- 1. About `doc-base' ------------------- Some time ago, there was a big discussion on the Debian mailing lists about the preferred documentation format in Debian because the current section in the policy manual about documentation contradicts itself (cf. bug #7890 (http://bugs.debian.org/7890)). The discussion showed clearly that people have very different opinions on that topic and thus, we'll have to implement a flexible solution so that everyone is pleased. 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 below) at installation time and de-register the manuals again once the package is removed. With this registration process, `doc-base' will be provided with details about the installed manuals, file names, documentation formats, etc. Based on the `doc-base' configuration which can easily adjusted by the local system administrator, `doc-base' will eventually convert between different documentation formats (where available, for example, texinfo source to GNU info or PostScript), optionally compress or remove HTML manuals which are also available in GNU info format, etc. etc. Since all manuals will eventually by registered, `doc-base' can also be used to solve another outstanding problem: Debian currently has two different online documentation systems, `dwww' and `dhelp'. Since both systems have their advantages and disadvantages, it has been decided to support both packages and let the system administrator choose which implementation he/she prefers. However, this requires all packages to support both online documentation systems. This can be done easily via `doc-base' (see below). In summary, `doc-base''s main functionality is: * convert online manuals between different documentation formats (depending on its configuration), and * register online manuals to Debian's online help systems, `dwww' and `dhelp'. Until now, only the second part has been implemented. ------------------------------------------------------------------------------- 2. The packages interface ------------------------- 2.1. Introduction ----------------- Each Debian package that installs online manuals (any format) should register its manuals to `doc-base'. This is done by installing a `doc-base' _control file_ and calling `install-docs' from the `postinst' script. 2.2. Document ids ----------------- Each piece of online documentation that is registered to `doc-base' must have an 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 Just as package names, the document id may only consist lower case letters (a-z), digits (0-9), plus (+) or minus (-) signs, and dots (.). 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. 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/doc/doc-base/doc-base.sgml.gz Format: text Files: /usr/doc/doc-base/doc-base.text.gz Format: HTML Index: /usr/doc/doc-base/doc-base.html/index.html Files: /usr/doc/doc-base/doc-base.html/*.html As you can see from this example, the syntax--just as 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 simply to remember the basic ideas. The syntax of the control file is simple: Empty lines seperate sections (see below). The other line use a field-value syntax. Field values may be wrapped over several lines if the first character of subsequent lines is a space; if the value should contain an empty line a single dot (.) has to be placed in the second column. The field names are case-insensitive. The first section of the control file describes the document, starting with the document id (the `Document:' field), the title, etc. This information will be used when the manual is registered to the online menu systems (`dhelp', `dwww', etc.). The following sections describe the different formats which are provided by the package. This information will be needed when the format-conversion feature is implemented. (Note, that these fields are likely to be changed as soon as I start with the implementation.) For now, only the format `HTML' is recognized. The `Index:' field has to contain the absolute file name of the title page of the document. (This file will be specified as front page link when the document is registered to `dwww' or `dhelp'.) 2.4. Registering documents using `install-docs' ----------------------------------------------- In order to register a piece of online documentation to `doc-base', the package has to install the control file (see above) as file `/usr/share/doc-base/'. Then, it should call `install-docs' from its `postinst' script: if [ "$1" = configure ]; then if command -v install-docs >/dev/null 2>&1; then install-docs -i /usr/share/doc-base/ fi fi and from the `prerm' script as well: if [ "$1" = remove -o "$1" = upgrade ]; then if command -v install-docs >/dev/null 2>&1; then install-docs -r fi fi With that, `doc-base' will automatically register the online manuals to `dwww' and `dhelp' 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 not empty ------------------------------------------------------------------------------- 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/doc/foo/sgml/foo.sgml.gz ---format-description--- Format: html Files: /usr/doc/foo/html-sgml/*.html Index: /usr/doc/foo/html-sgml/index.html ---status-information--- Control-File: ../foo-0.0/foo.desc Registered-to-dhelp: 1 Registered-to-dwww: 1 In some cases, `doc-base' creates files when installing a document. For example, when a document is registered to dhelp a file ``.dhelp'' is generated. You can check out which files have been created by `doc-base' with the ``-L'' or ``--listfiles'' options followed by the document id. Here is an example: $ install-docs -L foo /usr/doc/foo/html-sgml/.dhelp /usr/lib/menu/doc-base-foo ------------------------------------------------------------------------------- 4. TODO List ------------ The following items are listed, in approximate priority, as to-do items. Our first priority is to define the core issues of the Slink (Debian 2.1) Debian Documentation System, which will have status a Sub-Policy. * Policy: document the `doc-base' document registration file format separately (or SUBDOC it) as a proposed Debian documentation system policy. Discussion is underway at ; Adam Di Carlo is in charge of this. * Policy: define a first-cut standard as the document heirarchy. Discussion is underway at ; Marcus Brinkmann is in charge of this. * Documentation update: show clean and minimal use of `install-docs' from 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. * Determine a cleaner way to manage the various little files such as `.dhelp' and `doc-base' status files. This also involves behavior on remove or purge of the `doc-base' packges. I believe derived files such as `.dhelp' will eventually go away, since packages should understand the `doc-base' document registration control file format directly. * Internationalization. * Automated format conversion, including user preferences. ------------------------------------------------------------------------------- Debian `doc-base' Manual Christian Schwarz Adam Di Carlo ver. 0.7.11-0.woody1, 14 May, 2005