Bug#543293: Poor quality of documentation in /usr/share/doc/cyrus-common-2.2/README.Debian.database.gz

[Alejandro Forero Cuervo]

Package: cyrus-common-2.2
Version: 2.2.13-14+b3
Severity: minor


Very poor quality of documentation in
/usr/share/doc/cyrus-common-2.2/README.Debian.database.gz.

It includes completely irrelevant things such as what are the type of
people that the maintainer likes or dislikes, leaving one with the
impression that he's rather arrogant: he seems to think he's better than
people who just want to get cyrus working and couldn't be less
passionate about, OoOoOo, reading documentations about it's internals.
I'm refering to the paragraph that STARTS IN ALL CAPS, which should be
removed: it does not help set up Cyrus in any way.

Also, the document mentions:

   If the BerkeleyDB version is what was changed, you need to use the
   Berkeley DB upgrade utility in all db* databases.  See the manpages
   for db*_upgrade. Note that you need to use the db*_upgrade utility
   with the same version as given on the DBENGINE line of
   cyrus-db-types.txt.

Of course, if one doesn't have dbX-util installed (which, I'd guess,
covers a LARGE portion of all Debian boxes out there), one won't have
those manpages.  If there's something worse than documentation that
tells you that the maintainer won't like you for not reading
documentation, it's documentation that, in addition to telling you that
the maintainer won't like you for not reading documentation (which, erm,
you are), won't provide you with all the information you need to achieve
what the documentation was created to help you achieve.  I would suggest
that, after removing the aforementioned irrelevant paragraph (about how
the maintainer is “quite short on time lately”), a mention of dbX-util
is added, along the lines of:

  These utilities are typically included in the db*-util packages (for
  example, get db4.2-util package for BerkeleyDB 4.2's db4.2_upgrade).

Thanks!

-- System Information:
Debian Release: 4.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: i386 (i686)
Shell:  /bin/sh linked to /bin/bash
Kernel: Linux 2.6.18-6-k7
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.utf-8 (charmap=UTF-8)

Versions of packages cyrus-common-2.2 depends on:
ii  add 3.102                                Add and remove users and groups
ii  deb 1.5.11etch1                          Debian configuration management sy
ii  dpk 1.14.25                              Debian package management system
ii  gaw 1:3.1.5.dfsg-4                       GNU awk, a pattern scanning and pr
ii  lib 1.2.dfsg.1-2.1                       Heimdal Kerberos - ASN.1 library
ii  lib 2.7-18                               GNU C Library: Shared libraries
ii  lib 1.39+1.40-WIP-2006.11.14+dfsg-2etch1 common error description library
ii  lib 4.2.52+dfsg-2                        Berkeley v4.2 Database Libraries [
ii  lib 1.2.dfsg.1-2.1                       Heimdal Kerberos - GSSAPI support 
ii  lib 1.2.dfsg.1-2.1                       Heimdal Kerberos - libraries
ii  lib 1.2.dfsg.1-2.1                       Heimdal Kerberos - roken support l
ii  lib 2.1.22.dfsg1-8                       Authentication abstraction library
ii  lib 5.4.1~dfsg-12                        SNMP (Simple Network Management Pr
ii  lib 0.9.8g-15+lenny1                     SSL shared libraries
ii  lib 7.6.dbs-13                           Wietse Venema's TCP wrappers libra
ii  lib 2.1.20010518.SNAPSHOT-17.1           The original "Instant Message" sys
ii  net 4.29                                 Basic TCP/IP networking system
ii  per 5.10.0-19                            Larry Wall's Practical Extraction 
ii  pos 2.3.8-2+b1                           A high-performance mail transport 

Versions of packages cyrus-common-2.2 recommends:
ii  cyrus-pop3d-2.2             2.2.13-14+b3 Cyrus mail system (POP3 support)

-- debconf information excluded