Documentation Policy

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

Hi folks!

To summarize this discussion so far: I think everyone here agrees that we
should provide HTML and INFO.

So we currently have three options, both having their advantages and
disadvantages:

  (Arguments with `(-)' will become obsolete when deity is available, see
  below.)


  Option 1: Put HTML and GNU info manuals into seperate packages (if they
            require more disk space than 100k, together).

    Advantages:
      -  Great flexibility for the users. They can skip doc at all, or
         just install info or HTML, or both.
      -  No waste of bandwidth for downloading docs one does not need.

    Disadvantages:
      -  A little more work for the maintainers.
     (-) A few more packages in the archive (see below) and thus a little
         bit confusing for newbies (until deity becomes available).


  Option 2: Put HTML and GNU info manuals into one package.

    Advantages:
      -  Not much additional work for maintainers.
      -  Only few new packages (see below).

    Disadvantages:
     (-) Waste of disk space: everyone has to install both formats.
      -  Waste of bandwith: you have to download both formats all the
         time.


  Option 3: We ship .texi files and produce HTML and/or info files on
            demand (in the postinst script).

    Advantages:
      - No work for the maintainers.
      - Great flexibility (the sysadmin could even produce PostScript
        files when needed!).
      - No new packages necessary, no additional space in the Debian
        archive will be needed.

    Disadvantages:
      - Everyone needs "makeindex" and "texi2html" installed. (We could
        package these up in a "debian-doc-base" package.)
      - Installation process will get slower (especially on 386
        machines!).


Note, that ``deity,'' which is expected for Debian 2.0, will change this
scenario a bit:

   Option 1:
       disadvantage of too many packages will disappear, since deity will
       be capable of handling more packages with confusing the sysadmin

   Option 2:
       disadvantage of "wasted disk size" will disappear, since deity will
       allow the local sysadmin not to install files that match certain
       patterns, for example /usr/info/*


I'm sure deity will be available for 2.0 and we should definitely take
this into account for our decision now. I think we could live with both
disadvantages for a few months very well until deity is available.

My prediction is that while a few people will like option 3) very much, it
will be unacceptable by a few others. (People usually don't want to
compile docs when installing a firewall :-)

So I think we have to look for a consensus in options 1) and 2). 

I just wrote a little perl script that checks all packages in "hamm/main"
about how much disk space is required for /usr/info/*, alltogether. The
result is: 12814 kbytes. (This is actually so low, that we should stop
this silly discussion immediately ;-)

Because of this, I propose:

   - The packages that carry the info documentation should also carry the
html documentation.

   - If all docs in a package exceed a limit (say 1mb), it has to go in a
seperate package. (This is current policy anyways. We'd just have to
specify the limit.)

(BTW, I'm assuming that *.info.gz requires the same amount of disk space
as *.html.gz. I'm sure we find a way to use .html.gz files somehow.)


Any comments are welcome,

Chris

--                  Christian Schwarz
                     schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
Debian is looking     schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
for a logo! Have a
look at our drafts     PGP-fp: 8F 61 EB 6D CF 23 CA D7  34 05 14 5C C8 DC 22 BA
at    http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-logo/


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