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

About doc-base, dwww, dhelp, and everything else :)

>From reading the latest mails on the current discussions here on
debian-doc, I got the impression that we are not making any progress. 

Note, that we had these discussions a few times already, including the
"doc policy" discussion on debian-devel, and also the discussions on
debian-doc shortly after we started the DDP. Therefore, I'm not going
to answer the same questions all over again, but instead would suggest
that everyone who does not remember the last discussions should check
out our mail archives.

I'm only answering a few intrested questions here:

 Q: Why is this discussion not on debian-devel?

 A: Because debian-doc is the right list for this discussion. Simply
    enlarging the audience would not get us any further. However, if
    this is wanted, I could send a public announcement to debian-user
    and debian-devel that we are discussing these topics on debian-doc
    now, and that everyone is welcomed to join our discussion. (Please
    tell me if this is wanted.)

 Q: Why is cooperation between doc-base, dwww, and dhelp so bad?

 A: I made several attempts (in private email) to either merge dwww
    and dhelp or at least have them support a unique package
    interface, at the time when dhelp was introduced. Unfortunately,
    all these attempts failed. (I think the current discussions makes
    the reasons for this quite obvious.)

 Q: Why doesn't current policy at least `suggest' the use of dwww or

 A: There are several reasons:
     - people take policy suggestions very seriously
       (i.e., people would start filing bug reports against packages that
       don't follow these suggestions)
     - if policy would suggest that packages support two different
       types of _Debian native_ packages for the same purpose, this
       would be considered as a `bug in the Debian policy'
     - it would be even harder for newer, better systems to be created
       and supported if policy mandates the use of the existing systems
       (for example, we had this problem with the `md5sums' files that
       have been invented by debstd--a tool which has never been approved
       by the developers)

 Q: What was the consensus about document format conversion in the
    last discussions and what are main ideas behind the solution?

 A: In all discussions about this topic we noticed, that people don't
    want us to ship a single documentation format, but to give the
    user a maximum of flexibility. However, a lot of people run Debian
    on slow computer systems, so the solution has to be fast, too.
    Several different solutions have been considered:

      a) ship all possible formats in Debian packages
         ==> would generate a lot more packages--but we already have
             too many packages from the `default' user's point of view
         ==> would make the Debian distribution a lot larger (IMO, we 
             are already to big)

      b) make different formats available on our ftp server
         ==> for some users (e.g., most people in Europe) Internet
             access is expensive, so these people would not have easy
             access to all documentation
         ==> it would be a lot of additional work for our maintainers
             and archive maintainers, since the documentation files would
             have to be updated with every new package upload
             (Note, that we are not talking about Debian manuals like
             the `Policy Manual,' but about a lot of small manuals like
             the GNU info manual of bash, for example.)

      c) ship only the documents source format and convert this into
         the preferred format at installation time
         ==> too slow on most computers
         ==> some conversions require a lot of other packages to be

    We finally ended with a compromise: (Note, that this compromise
    has actually been detected twice: First, there was a discussion on
    debian-doc about documentation formats of DDP-native documents.
    After a long discussion we ended with exactly this compromise.
    A few weeks later, there was the long discussion about a new
    documentation policy on debian-devel--without considering
    the results of the debian-doc discussions, we ended up with the
    same compromise. In my eyes, this is a proof that the compromise
    is reasonable and that we'd get the necessary majority to
    introduce it in the policy manuals, finally.)

      d) ship plain HTML files _AND_ the document source format in
         the packages
         ==> most user will only need HTML files (i.e., installation
             is very fast since no conversion has to be done)
         ==> the users who want some special format (e.g., PostScript
             for printed documentation) can easily generate these
             formats, either at installation time or at any time later

 Q: Is it a problem that doc-base is written in Perl?

 A: No. Perl is fast enough for our purposes here--even on slow

    Note, that doc-base will eventually become a very important part
    of the Debian distribution. We will eventually consider giving it
    a very high priority, perhaps tag it even `Essential' or
    distribute it in our base systems. Therefore, special care should
    be taken that doc-base only `Depends' on parts with also have a
    high `Priority.'

    As Perl has proven to be a very useful language for such tasks,
    we've decided (with the necessary majority under all developers),
    to include a subset of the Perl package, `perl-base,' in the base
    system and tag it `Essential.' This guarantees, that Perl and a
    subset of its modules is installed on all Debian systems. 



--                  Christian Schwarz
                   schwarz@monet.m.isar.de, schwarz@schwarz-online.com
                  schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
                PGP-fp: 8F 61 EB 6D CF 23 CA D7  34 05 14 5C C8 DC 22 BA
 CS Software goes online! Visit our new home page at

To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org

Reply to: