Documentation Policy

[Christian Schwarz <schwarz@monet.m.isar.de>]

Hi folks!

The "html vs. info" discussion reminds me of "vi vs. emacs" discussions
:-)

It's pretty clear to me that we'll have to support "info" in the future,
since we would have to drop the "GNU" from "Debian GNU/Linux" otherwise.

However, HTML is getting more and more popular these days and I think it
would be very unwise not to choose HTML as "preferred document format".

To summarize this: We'll provide HTML documentation where possible. In
addition, all texinfo manuals will be distributed in the info format, too. 

This can easily be accomplished by creating new packages carrying the info
and html docs, respectively.

For example, the current emacs package installs about 1mb of info docs in
/usr/info/emacs-info. I suggest to split this off into a new package
called "emacs-doc-info". In addition, we should create an "emacs-doc-html"
package. This way, the user (actually, the sysadmin) can choose whether
he/she wants to have a)  no document, b) info docs, c) html docs, or d)
both. 

I know, this means a little more work for the maintainers, but it's
definitely worth it!

So I suggest the following policy. Note, that this is just a summary, not
the actual text.


     The unification of Debian documentation is being carried out via
     HTML. However, we'll still provide GNU info documentation, where 
     available.

     Thus, every package that contains documentation in a convertable
     format has to provide HTML documentation. 

     The documentation will be distributed via several packages:

           foo-doc-html      for HTML docs
           foo-doc-info      for GNU info docs (where available)
           foo-doc-xxx       for other formats (only where appropriate)

     (An example for the last case would be "DVI" documentation for TeX
     related packages.)

     If the documentation files in all available formats do not require
     more than 100k of disk space _together_, they may be included in the
     "main" package. Otherwise, the will have to be distributed in
     seperate packages, one for each format.


Any 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 .