[Mimedefang] documentation bug/omission for newbies

[starlight.2016q2 at binnacle.cx]

At 02:58 4/19/2016 -0400, Steffen Kaiser skmimedefang at smail.inf.fh-bonn-rhein-sieg.de wrote:
>On Mon, 18 Apr 2016, starlight.2016q2 at binnacle.cx wrote:
>
>> I just spent a day butting my head against the fact that filter_begin() 
>> is _always_ passed a multipart MIME message container that _never_ has a 
>> useable $entity->bodyhandle().  This is not mentioned *anywhere*.
>
>hmm, I would not rely on this assumption.

Thank you Steffen for your reply.

I looked, and one positively for certain can rely on it:

in mimedefang.pl version 2.78 at line 6008:

   # Make entity multipart
   my ($code);
   $code = $entity->make_multipart();     # line 6010
   $WasMultiPart = ($code eq 'ALREADY');

   # If there are multiple Subject: lines, delete all but the first
   ...

   # Call pre-scan filter if defined
   if (defined(&filter_begin)) {
   push_status_tag("In filter_begin");
      filter_begin($entity);              # line 6025
   ...

>> I'm still having trouble seeing it--apologies. . .
>
>because MIMEDefang internally breaks up the message into parts
>anyway and feeds all parts to filter(), I would construct your
>code like so:

[code omitted]

Yes thank you, but this confirms my point that no simpler
approach exists.  The code is a state machine that invokes

   "scan that part"

only for the first pass through filter().  "scan that part"
consists of 10 out of the 18 lines in the solution I arrived
at.  The state machine is slightly more than the 8 lines
of equivalent overhead in my "directly access the body
part" solution.

Either solution requires one to spend some time learning
the MIME-tools APIs.  I like MIME-tools!

The point behind my posting is that when a newbie (me)
first arrives at MIME-tools and reads through it (late
at night and a bit tired I might add), they come away
with the strong impression that if a message is
single-part, the $entity object will arrive with the
body attached and accessible via the bodyhandle() call.
Due to fatigue and a reliance on the unembellished
MIME-tools docs I spent several hours getting it to
work, but ended up with a solution that was about two
lines different than the first attempt.  So all I'm
saying is that the "guaranteed multipart" state of
$entity as passed to the filter*() callbacks deserves
a sentence or two in the man page

   mimedefang-filter(5)

in the paragraph under section

   FILTER, $entity

I do find the behavior quite sensible BTW.

Regards