[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ A ] [ next ]


Debian Documentation Policy (DRAFT)
Chapter 3 - Debian Manuals

The DDP considers a Debian Manual to be any piece of documentation created to address the needs of users of Debian system or developers in the Debian project.

FIXME:The documentation which comes with application software packages and installed in such places as /usr/share/doc/packagename*.txt.gz or /usr/share/doc/packagename/html/* are not the focus of this chapter at this moment.

Debian Manuals are moving targets in the sense that they should be constantly be updated to include relevant information related to the object that is being documented. Some of the manuals the DDP currently holds are:

Here, some documents are not directly under DDP:

Manuals are usually of interest to a wide variety of people across all countries and as such should be translated. This helps avoid problems with language barriers and manages to make Debian more useful to people all over the world.

The DDP provides resources for Debian manual writers, translators and reviewers. These resources help co-operation between all the different people responsible to making a document available to those that wish to read it. Thus, the framework provides:

The placeholder for the DDP manuals section in the CVS server is the manuals.sgml directory. Documents under that directory must follow the following policies

3.1 Source file format

SGML is used as the source format for all manuals. Both SGML format compatible with the debiandoc-sgml [6] tool chain (DTD version 1 or later) and Docbook [7] (SGML or XML, the 4.1.2 version or later). For the time being the default article style [8] might need to be used.

Note: To translate from debiandoc-sgml format to docbook-xml please obtain and install latest tool from DDP CVS by: 

      $ cd $HOME
      $ echo 'export PATH="~/Debiandoc-to-docbook:${PATH}"'>> ~/.bash_profile
      $ . ~/.bash_profile
      $ export CVSROOT=:pserver:[email protected]:/cvs/debian-doc
      $ cvs login
      $ cvs co -d Debiandoc-to-docbook utils/debiandoc-to-docbook
      $ cd Debiandoc-to-docbook
      $ cd /some/debiandoc/sgml/source-directory/   # use of mc is easy way :)

This script translates from debiandoc-sgml to docbook-xml with an XSLT stylesheet. Please read README and dd3xml.html in this archive for the details.

When to you use which format? Docbook needs not be the chosen always as the only documentation format. Debiandoc-sgml is preferred for most manuals since:

However, the debiandoc-sgml DTD does have some drawbacks including:

So, stick with debiandoc-sgml unless you need tables, figures, optional framed output and such.

The other options for the source file format were: LaTeX, HTML, texinfo, groff and several other minor formats. Even if some of these were used at some point by DDP documents their use is not supported. All DDP manuals must be provided either in debiandoc-sgml or docbook (sgml or xml) format (this rule does not necessarily apply to other documentation that is handled by the DDP)

FIXME: Add links to relevant discussion on the mailing list, such as:

FIXME: Discuss translation of documents and reference PO translation of debiandoc documents and i18n and documentation (discuss needs of reviewers and translators).

3.2 How to start a manual

If you think a manual is missing in the Debian Documentation Project and want to contribute writing it first (or have it already written) please follow this procedure:

3.3 How are documents published?

Documents under the manuals.sgml are compiled and published through a chain of Makefiles. The Makefile under the root dir includes a definition of which subdirectories will be handled in the chain. This makes the Makefile go through each of the subdirs and compile the documents.

All documents must hold a Makefile in the main directory. Contents of this Makefile must be derived from the ones included in the Makefile.common, this file includes common definitions (such as publish) which will be used when compiling and common variables (such as the place where to install the compiled documentation) that should not be modified.

Following make target are used:

Following make variables are used:

3.4 Published file formats

In order to provide readers for different methods to access documentation, we strive to publish contents in all the following formats:

3.5 File names and their locations

In the following section, the choice of the file names and their locations are explained. Here following conventions are used:

3.5.1 Upstream SGML source

DDP run CVS server and keep upstream SGML source (or its copy). 

       CVSROOT=:pserver:[email protected]:/cvs/debian-doc 
       Repository: ddp/manuals.sgml/manualname/

After obtaining concensus in [email protected] one can start new directory as follows: 

     $ cd someplace
     $ CVSROOT=:pserver:[email protected]:/cvs/debian-doc
     $ export CVSROOT
     $ cvs co ddp/manuals.sgml/
     $ cd ddp/manuals.sgml/
     $ mkdir new-ddp-manual-name
     $ cvs add new-ddp-manual-name
     $ cvs ci
     ...

3.5.2 Debian packages

FIXME: write about why you need to make Debian packages. And also how to make them easily.

3.5.2.1 Source packages

The Source package contains the SGML source only

The latter format is preferred even if you are the upstream maintainer.

If the source consists of multiple files, you are encouraged to keep them in one specific subdirectory per language.

FIXME: Adam believes that it could be possible to distribute the SGML source _only_ and creating the formats the user wants to have at runtime (could be installation time as well as afterwards). This has several advantages:

Some disadvantages are:

This has also been discussed recently (see http://lists.debian.org/debian-doc/2002/debian-doc-200212/msg00097.html)

3.5.2.2 Binary package:

The Binary package provides the documents in each of the proposed formats for offline reading. Binary packages should include all the formats for which the document compiles. As for translations, they should be provided as separate packages if the binary (with all the available translations) exceeds five megabytes in size (see below for the appropriate naming for these binary packages).

Depending on wether or not translations are provided in different binary packages the package naming will be:

FIXME: this is debatable. Currently many package name packagename_version_all.deb just install the English original. Some people feel that the use of the name for the English package, packagename-en_version_all.deb should be discouraged.

3.5.3 Files installed by the Debian package (Option1)

In order to make DDP documents easy to find, use of /usr/share/doc/Debian/ has been adopted as the central location. Currently this file location is under discussion.

3.5.4 Files installed by the Debian package (Option2)

In order to make DDP documents easy to find, use of /usr/share/doc/Debian/ has been adopted as the central location. Currently this file location is under discussion.

Note: having /usr/share/doc/packagename-LANG/ also helps if we want to help people use locale-purge for documentation too. (javi)

If so, we need symlink in /usr/share/doc/Debian/ while /usr/share/doc/packagename-LANG/ should contain real files. (osamu)

3.5.5 Files on WWW server (DDP, CVS generated)

These are created with publish target. PUBLISHDIR is used to locate directory to install documentation where http://www.debian.org/doc/manuals/ is pointing.

3.5.6 Files on WWW server (stable version)

Stable version of documents are installed from released package to DDP web page with a script un-compressing files.

FIXME: How is this install automated? Explain the process. We might need ftp-masters to allow access without an upload.

3.5.7 Files on FTP server

DDP documents need to be published in Debian's ftp servers (and mirrors) in order to provide another mean for retrieval to users. The placeholder for this documentation is ftp://ftp.debian.org/doc/

FIXME: Determine how this is going to be automated (contact ftp-masters). The /doc should be handled exclusively by the DDP team.

FIXME: this is an idea (Osamu). Permissions, etc. need to be fixed too.

FTP files are created with publish-ftp target in top most Makefile which uses publish target in the subdirectories to create file in FTP area by using proper PUBLISHDIR.

3.6 Files on CD-ROM ISO images

FIXME: This needs to be more homogeneous.

The current debian-cd program is used to build the ISO images for official Debian CD-ROMs. This program extracts documentation to be placed in the CD-ROMs so that users can access this documentation without needing to install Debian at all (even if later on they could install the same documentation just by installing the appropriate packages).

Not all DDP documents are placed on the CD-ROMs since once of the issues on these ISO images is how to distribute the available size so that all the necessary software is available in the first CD-ROMs (so that users do not need to download all the CD-ROMs in order to have a functioning Debian installation). Thus, only important documentation (usually oriented towards users) is placed there. This usually includes documents such as: The Debian FAQ, The Installation Manual, etc.

FIXME: Check if this is true. Also for text, directory are better to use full locale such as en_US.UTF-8/ which is not the case in Debian.

Debian-cd takes the available documentation from different sources: the primary FTP server and some documentation packages installed in the system where the script is run.

Note: Providing a sensible location of documentation in the packages as well as translations makes it possible to have debian-cd make localized CD-ROMs that not only include the installation in a given language but provide the documentation in that language too!

3.7 Best practices

This section describes few recommended practices but these are not an enforced part of the DDP policy.

3.7.1 index.html

Currently, many generated HTML files still create index.html or index.LANG.html as the starting page but these are discouraged practices since they hide other files. (FIXME: This is debatable. It is implemented for the Debian Reference but makefile is a mess.)

3.7.2 Debian web page entry style

user-manuals.wml entry shall be: 

     <availability>
     <released name="release-name" path="path-in-web-site">
     <inpackage "package-name">
     <released name="package-name" index="index-name" path="package-location"
                   langs="en fr it es" formats="html txt pdf ps">
     <inddpcvs name="cvs-location" langs="en pt-br ru" cvsname="cvs-name">
     </availability>

For packages which has released version, use "released" instead of "inddpcvs" to create the web page.

3.7.3 LaTeX/TeX

In order to reliably produce PS and PDF files, it is recommended to include a texmf/texmf.cnf file which only lists those key parameters (i.e., things like pool_size) which you need to have them large enough for the proper building environment.

Then Makefile has to use it through the environment variable: 

     TEXMFCNF=texmf:
     export TEXMFCNF

Here, the trailing colon is critical. This will ensure rest of parameters to be taken from the system's current default value and avoids TeX version dependencies for the SGML source as well prevents FTBFS bug problems.

If you are running specifically LaTeX, then you may want to have: 

     pool_size.latex = whatever

to specify that you want it to apply to LaTeX; otherwise a specific one in the /etc/texmf/texmf.cnf file might override yours.

Alternatively, you can also specify pool_size etc. as environment variables, which will override the texmf.cnf settings.

3.8 TODO

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ A ] [ next ]

Debian Documentation Policy (DRAFT)


CVS, Fri, 10 Aug 2007 19:31:26 +0200

Debian Documentation Project [email protected]
Authors, Section A.1