[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Next approach: Documentation Policy



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
                    schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
Don't know Perl?     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.perl.com     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: