Bug#386758: uw-mailutils: mailutil documentation is incomplete

2006-09-09 Thread Ross Boylan
Package: uw-mailutils
Version: 7:2002edebian1-13
Severity: minor

The mailutil man page says, in the Arguments section
  The arguments are  standard  c-client  mailbox  names.   A  variety  of
  mailbox  name formats and types of mailboxes are supported by c-client;
  examples of the most common forms of names are:
and later
  See your system  manager  for  more  information  about  the  types  of
  mailboxes which are available on your system.

This poses two challenges.  First, there is no obvious place to
discover what the standard c-client mailbox names are, and I don't
think this binary package (uw-mailutils) has that information
anywhere.  This meant, for example, when I saw references to /ssl in
the FAQ I didn't even know where it went.

I was interested only in mailutils, not the full server (I use cyrus,
and the docs specifically recommend using the UW tools for migration).

Second, the person who installs this package (that's the system
manager) is not in a good position to know which types are available.
Only the packagers know this.

Marc Crispin referred me to the file naming.txt in the docs directory
of the source for more info, with naming.txt and drivers.txt of
possible secondary interest.  naming.txt had the information I was
looking for.  He also said the man page can't be more specific because
the precise options available depend on how the program was compiled.

I can imagine at least two solutions to this problem.  The minimalist
one would be to include the relevant source docs files in
/usr/share/doc/uw-mailutils/, and have README.Debian alert the user to
their existence and to which options are supported in the Debian
package (and/or which other facilities are needed for the different
options to work).

The maximalist approach would be to fold the necessary information
into the man page (or maybe some other man page on c-client
information).  Ideally this would go upstream, though upstream seems a
bit reluctant.  I think it's both more typical and more desirable to
document all the options, and note that some of them may not work.
This way, material could be customized to the local system by simple
deletion (it could even be done by clever config magic, I imagine).

-- System Information:
Debian Release: testing/unstable
  APT prefers testing
  APT policy: (990, 'testing'), (990, 'stable'), (50, 'unstable'), (1, 
'experimental')
Architecture: i386 (i686)
Shell:  /bin/sh linked to /bin/bash
Kernel: Linux 2.6.16-2-686-smp
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)

Versions of packages uw-mailutils depends on:
ii  libc-client2002edebian 7:2002edebian1-13 UW c-client library for mail proto
ii  libc6  2.3.6.ds1-4   GNU C Library: Shared libraries
ii  libcomerr2 1.39-1common error description library
ii  libkrb53   1.4.4~beta1-1 MIT Kerberos runtime libraries
ii  libpam0g   0.79-3.1  Pluggable Authentication Modules l
ii  libssl0.9.80.9.8b-2  SSL shared libraries

uw-mailutils recommends no packages.

-- no debconf information


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]



Bug#386758: uw-mailutils: mailutil documentation is incomplete

2006-09-09 Thread Ross Boylan
The two additional documentation files were drivers.txt and
formats.txt.  I gave the main one, naming.txt, twice in my original
message.


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]