doc-base: next proposal for doc policy
Here is another proposal for our new "Documentation Policy". I tried
to cover all arguments and ideas that have been presented to
debian-devel in the last days/weeks. (If really all people
participating in this discussion want to have that much documentation,
Debian will become the best-documented Linux distribution in the next
Note, that this is not the actual text that will be included in the
Policy Manual, but a list of statements such a text will be based on.
- HTML is the "default" markup format.
- GNU info is supported, as well.
- packages should be kept small (don't waste bandwidth)
- we can't afford lots of new packages (there are too many to
- we should try to minimize the necessary disk space
- some people have slow computers (can't afford on-installation
or on-the-fly processing)
- some people need "secure" computers (can't run a web server)
- Debian 2.0 will include deity, which can remove files
that match certain patterns
- some people want to have printable versions of documents
(compressed PostScript documents)
The unification of Debian documentation is being carried out via HTML.
Thus, every piece of documentation that is available in a format which
can be converted into HTML, should be converted, with the exception of
manual pages and source code examples. (Manual pages can easily be
converted at run-time via dwww.)
In case of converted HTML documentation, the files with the original mark
up format should not be included, unless they are considered as "example
documents" for that mark up language.
The HTML files are included _uncompressed_ in the package (.deb) since
this is the most easiest way to read the manuals.
Packages that contain programs with GNU info manuals, should provide
the manuals in HTML _and_ in GNU info format. The HTML files should be
stored in the directory
All documentation related files will be kept in the "main binary package"
if they do not exceed 500 kbytes installed size together. (Of course,
documentation-only packages are not covered by this rule.)
Every package that includes HTML and/or INFO documentation has to
support the "doc-base" package (which will be created soon). This
package will have the following functionality:
- opt. ask the user at installation time if he/she wants to
compress all HTML docs (he/she can do this, if he/she has a web
browser that can read .html.gz files or if he/she has a web server
that can do this) Note, that the contents of the .html files
(i.e. links) will _not_ be touched. (These newly created .html.gz
files will be removed in the postinst script, automatically.)
- opt. remove all INFO docs /usr/info/*, if the user doesn't
want to have these
- opt. remove all INFO-converted HTML docs
/usr/doc/*/html-info/*, if the user doesn't want to have these
- the three options above will be asked in the postinst script,
unless they are predefined in some /etc/doc.conf configuration file
In addition, the doc-base package will include a (short) description
of the ideas behind the "Debian Documentation Policy" (the results of
this discussion), as well as a description of how to fine-tune his/her
web browsers/servers to serve .html.gz files, etc.
All GNU texinfo manuals, as well as all other formats that can be
converted into PostScript files, should be converted into PostScript
compressed, and uploaded to ftp.debian.org:/debian/doc/.... (the directory
name will be defined soon). Since the manuals are one file each and since
nearly all (if not all) Debian CDs include the doc/ directory, there is no
need to package up these files. The user can easily download them
individually, or all together, read them online, etc.
Any comments? (I'm sure ;-)
-- Christian Schwarz
PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
CS Software goes online! Visit our new home page at
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
email@example.com . Trouble?
e-mail to firstname.lastname@example.org .