Debian Bug report logs - #622621
missing/incomplete documentation

Reply or subscribe to this bug.

Toggle useless messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Alexander Zangerl <az@debian.org>

To: Debian Bug Tracking System <submit@bugs.debian.org>

Subject: missing/incomplete documentation

Date: Wed, 13 Apr 2011 22:58:38 +1000

Package: mlmmj
Version: 1.2.17-2
Severity: normal

during a recent list conversion to mlmmj i've run into a number of
issues where the mlmmj documentation isn't complete, missing or incorrect.

* README.listtexts
  is completely missing from the package; looks like upstream put it
  on the website but not in the vcs.

  README.listtexts doesn't mention that texts are read not just 
  from the listdir - but also from /usr/share/mlmmj/text.skel/default
  and /usr/share/mlmmj/text.skel/en: the first existing text file of 
  a given name will be used.

  README.listtexts doesn't mention that most of the substitutions 
  don't work across the board; for example, $maxmailsize$ isn't expanded in
  either help or faq text, $originalmail$ isn't available during 
  subscription moderation and so on.
 
  this needs to be fixed; ideally all substitutions should work
  everywhere (minus where there isn't any context, e.g. $originalmail$ 
  for help or faq), but until then the README file should at least spell out
  what works where (see 'data' arg to prepstdreply() in mlmmj-*.c).

 * README and delimiter
  coming from other mailinglist software it's not obvious why 
  mlmmj is interested in the local/part delimiter in email addy's
  - most other list managers use separate addresses.
  
  README should mention that mlmmj uses listname+allkindsofthings@domain
  to distinguish between functions, and that listname+* must be routed to
  mlmmj-recieve.

* TUNABLES
  the footer mechanism isn't mentioned anywhere except in the main README;
  it should be briefly mentioned somewhere near the customheader 
  explanation.

  mention that the customheaders file mustn't contain any blank lines, 
  or the headers of your outgoing mail will be wrecked (the blanks 
  aren't removed, dumpfd2fd.c doesn't have the smarts and 
  do_all_the_voodo_here() doesn't help it along either).

  for delheaders it's even worse: a blank line there will REMOVE 
  ALL HEADERS! (findit() in do_all_the_voodo_here.c happily says
  match because strncasecmp with n=0 always matches).
 
* sendmail and headers: 
  the default program mailer doesn't provide a Return-Path,
  but mlmmj can't live without one (with other mtas it uses SENDER from the 
  environment, but sendmail doesn't provide that either).

  how to make the shell mailer send a return-path is hidden too well in
  README.sendmail (=as an aside while discussing the verp hack); it should 
  be stated more prominently. I'm thinking of something like this, 
  before the verp hack:
 
  Sendmail + mlmmj:
  -----------------

  mlmmj needs the Return-Path header, and sendmail's program mailer 
  doesn't include that by default. 
  You'll need to add the following to /etc/mail/sendmail.mc, 
  make sendmail.cf and reload sendmail:
  
   dnl make mlmmj happy: add return-path header
   define(`LOCAL_SHELL_FLAGS',`eu9P')dnl
  
* verp
  the TUNABLES implies (to me at least) that verp isn't used unless 
  asked for, but that's not correct: by default (= without control/verp),
  mlmmj simply sends one mail per conversation and does the verp "by hand".
  mlmmj does only use a static envelope from if staticbounceaddr is set.
  
  the TUNABLES entry on verp should state that it enables *mta-based*
  verp where possible, and that without staticbounceaddr mlmmj does verp 
  by hand.
  
* verp and sendmail
  README.sendmail shows a complex hack for making sendmail offer verp, 
  but it doesn't state anywhere that verp "by hand" works just fine. 
  the hack also embeds list configs in the sendmail.mc, and as given doesn't
  work for more than a single list on this host (the regex map is    
  very specific). 
  because of this limitation and the fact that "manual" verp works just fine
  i believe the hack should be labelled optional - right now the 
  (incorrect) explanation of verp in TUNABLES plus the README.sendmail 
  implies that you have to hack up your sendmail to get verp
  going at all, which isn't true.

* mlmmj-maintd
  manpage doesn't mention the fixed sleep time (7200s) between runs when 
  in daemon mode.

* mlmmj.operation.log
  nothing ever mentions that some mlmmj operations will be logged in 
  the list dir, in mlmmj.operation.log. (but then the logging situation
  in mlmmj is pretty dire anyway.)

that's it for now; i've given this severity=normal because i think some
of those missing info bits affect a smooth deployment of mlmmj quite badly.

regards
az

Message #12 received at 622621@bugs.debian.org (full text, mbox, reply):

From: Thomas Goirand <thomas@goirand.fr>

To: Alexander Zangerl <az@debian.org>, 622621@bugs.debian.org

Subject: Re: Bug#622621: missing/incomplete documentation

Date: Wed, 13 Apr 2011 22:30:47 +0800

On 04/13/2011 08:58 PM, Alexander Zangerl wrote:
> during a recent list conversion to mlmmj i've run into a number of
> issues where the mlmmj documentation isn't complete, missing or incorrect.

Hi. Thanks a lot for all this, it is very interesting, important and
helpful. I will definitively try to pay attention to all your
suggestions, and will fix all.

> that's it for now; i've given this severity=normal because i think some
> of those missing info bits affect a smooth deployment of mlmmj quite badly.

Sorry, but I don't agree with that. I've set it to wishlist, as this is
what it deserves for an issue with documentation. Note that I really
think that maintenance work on bug issues wont depend on the severity
(at least, it shouldn't), and even with severity wishlist, I will work
on it as soon as I have a bit of free time (which I believe will be
quite soonish).

By the way, this package is team maintained, and currently, I'm the only
active DD behind it. I think MLMMJ deserves more love: it's to me the
best list manager ever. So if you'd like to help, that'd be great as
well (our Alioth group and git are open to contributions).

Thomas

Send a report that this bug log contains spam.