new approach: Documentation Policy
Hi folks!
I think most people here agree, that we should ship "*.texi" files
instead of "*.info" files, since "makeinfo" is fast enough and the
user does not have to fetch the source package in order to get a
PostScript printable manual.
So here is yet another proposal for the new "Documentation Policy". As
always, I tried to cover all arguments and ideas that have been
presented to debian-devel in the last weeks.
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.
Assumptions:
- HTML is the "preferred" (i.e. 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
handle anyways!)
- 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)
- some people want to have printable versions of documents
(compressed PostScript documents)
- "makeinfo" is fast enough on all computers
- on-demand formatting of manual pages is fast enough
Goals:
- unification of documentation formats (i.e. HTML)
- support of "old" formats (GNU info)
- great flexibilty (sysadmin can choose what he/she wants)
- not much additional work for the maintainers
- no additional feature requests for dpkg (since changes in dpkg
can take a long time)
---------------------
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.)
Manual pages will still be distributed in compressed source code,
since on-demand formatting is quite fast and it is also possible, to
get nice printable output (via `man -t') if needed.
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. (.texi files are an exception to
this rule, see below.)
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_ texinfo source (i.e. "*.texi") format. The
HTML files should be stored in the directory
/usr/doc/<pkg-name>/html-info/
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 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. (One can do this, if one has a web browser that can read
.html.gz files or a web server that can decompress the files on-the-fly.)
Note, that the contents of the .html files (i.e. links) will _not_ be
touched in either case. (The newly created ".html.gz" files will be
removed in the prerm script, automatically.)
- opt. remove all GNU info-converted HTML docs
/usr/doc/*/html-info/*, if the user doesn't want to have these
- opt. compile "*.texi" files into GNU info files
- opt. compile "*.texi" files into PostScript format
- the 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 one can fine-tune
the web browsers/servers to read .html.gz files, etc.
---------------------
Notes:
1. This approach does not depend in any way on special "deity
features". It can fully be implemented with the current versions of
dpkg and dselect without any problems. (Of course, this does not make
"deity" obsolete :-)
2. The statement, that PostScript files should be created and uploaded
to the ftp server, has been dropped, since this would have been too much
work for the developers and everyone can create PostScript files on
demand.
3. There is no need for a unification of the paper format (A4 or
letter) since all PostScript manuals are created on-demand only, where
the sysadmin can specify which formats he/she wants to have.
Comments?
Thanks,
Chris
-- Christian Schwarz
Do you know schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
Debian GNU/Linux? schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
Visit PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
http://www.debian.org http://fatman.mathematik.tu-muenchen.de/~schwarz/
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-request@lists.debian.org .
Trouble? e-mail to templin@bucknell.edu .
Reply to: