Hi folks!
Here is another proposal for our new "Documentation Policy". This
time, I have added a list of assumptions, on which this proposal is
based on.
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 "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)
- 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 have to be installed _uncompressed_ since there is no
easy way to do on-the-fly decompression, yet. (A few web browsers and
a few web servers can do this, but we can't force our users to run a
web server, nor which server to run, nor which browser to use.)
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
/usr/doc/<pkg-name>/html-texi/
This way, the local sysadmin can decide, whether he/she wants to have
GNU manuals in info format (/usr/info/*), or in converted HTML format
(/usr/doc/*/html-texi/*) by setting "filter rules" in the new package
management system (deity), which will be available for 2.0.
All GNU texinfo manuals will be converted into PostScript, compressed,
and packaged up in a single "gnu-manuals" package. This way, only the
people intrested in these "printable" manuals need to download
them. This package can be updated every 4 weeks, for example, to
minimize maintainers' work.
(Note, that other maintainers are encouraged to provide compressed
PostScript files in extra packages, as well.)
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.)
---------------------
Note, that I have dropped the html.gz/fixhtmlgz issue completely. The
only possible way, as it seems to me, is to support a compressed
filesystem, but these are not ready for real use, yet.
Any comments? (I'm sure ;-)
Thanks,
Chris
(Debian Policy Manager)
-- Christian Schwarz
[EMAIL PROTECTED], [EMAIL PROTECTED],
Don't know Perl? [EMAIL PROTECTED], [EMAIL PROTECTED]
Visit PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
http://www.perl.com http://fatman.mathematik.tu-muenchen.de/~schwarz/
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
[EMAIL PROTECTED] .
Trouble? e-mail to [EMAIL PROTECTED] .
