267022 - email_in.pl: documentation for email gateway very difficult to find although referenced

Status: ASSIGNED

(Bugzilla :: Documentation, defect)

Description

[Steve Weisberg]

User-Agent:       Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)
Build Identifier: 

There are several references to an email gateway (api), most detailed in Most 
detailed reference is in CVS section (4.6.2). It's implied that there is a 
section title Email Gateway. The only real instruction is buried in the FAQ 
and that is a pointer to an installation file. I suggest either pointing 
directly to the installation file anywhere email gateway is discussed or 
copying the readme.mailif file as a section in the documentation. 

Doing the "finds" to finally have found the faq reference was very difficult 
in the PDF (the nature of the beast). I only traced it when using the txt 
versio of the documentation.

Thanks.




Reproducible: Always
Steps to Reproduce:
1. See description. No more to add.

Actual Results:  
See description. No more to add.

Expected Results:  
See description. No more to add.

Comment 1

[Dave Miller [:justdave]]

And this is still the case, even though we now have an officially supported email system instead of the one in contrib.  The FAQ item is the one and only reference to it in the main documentation.

Comment 2

[Colin Ogilvie [:cso]]

Taking

Comment 3

[Colin Ogilvie [:cso]]

Attachment: User Documentation

User documentation based off of the POD in email_in.pl.

Generated documentation at http://landfill.bugzilla.org/csodocs/email_int/using.html

I'll write documentation for the 'Admin' for enabling it later.

Comment 4

[Frédéric Buclin]

Comment on attachment 295613 [details] [diff] [review]
User Documentation

>+    <title>Incoming Email Interfaace</title>

Interfaace -> Interface

Comment 5

[Colin Ogilvie [:cso]]

Dodgy typing on my part :)

Comment 6

[Max Kanat-Alexander]

Comment on attachment 295613 [details] [diff] [review]
User Documentation

  What I'd like to see is some way of linking to the API docs for some of this, because the API docs will always be up-to-date and these docs might not be, and I'd like to avoid duplication of effort. That is, anything already said in the API docs should be linked to, ideally, but anything else can live here. However, if you don't think that's reasonable, we don't have to do it.

>+      <para>
>+        The reamining fields

  remaining

> that can be filled are as follows (these are
>+        not required by default, and should only be used if you wish to set
>+        them).

  For some of them, that's only true if there's a default set in editparams. Did you see the docs for Bugzilla::WebService::Bug::create? The thing to note is that WebService::Bug::create uses some aliases that email_in doesn't support. That is, email_in only supports what shows up in fielddefs as the name. (For example, "summary" won't work for short_desc.)

Comment 7

[Colin Ogilvie [:cso]]

(In reply to comment #6)
> (From update of attachment 295613 [details] [diff] [review])
>   What I'd like to see is some way of linking to the API docs for some of this,
> because the API docs will always be up-to-date and these docs might not be, and
> I'd like to avoid duplication of effort. That is, anything already said in the
> API docs should be linked to, ideally, but anything else can live here.
> However, if you don't think that's reasonable, we don't have to do it.

The API docs shouldn't be describing how to do something from an end-user perspective, surely. The API docs should be describing how to do something from a user of the code's perspective. So for Bugzilla::WebServices stuff, I'd recommend pointing people to the API docs as they'll obviously need to know the API but not in this case. I don't consider the email interface as an API in that sense - I consider it like the Web Frontend.

>+      <para>
> >+        The reamining fields
> 
>   remaining

D'oh.


> > that can be filled are as follows (these are
> >+        not required by default, and should only be used if you wish to set
> >+        them).
> 
>   For some of them, that's only true if there's a default set in editparams.
> Did you see the docs for Bugzilla::WebService::Bug::create?

Yes - The descriptions in the attached document were taken from there in the first place.

> The thing to note
> is that WebService::Bug::create uses some aliases that email_in doesn't
> support. That is, email_in only supports what shows up in fielddefs as the
> name. (For example, "summary" won't work for short_desc.)

I believe I've noted the cases where they differ in the list.

Comment 9

[Frédéric Buclin]

It would be nice if the documentation was also able to describe how to confiugure the system correctly to automatically redirect incoming emails to email_in.pl, as suggested in the bug I just marked as a dupe. I think importxml.pl already has some doc about this topic, which may be good to share with email_in.pl.

Comment 10

[Larsen]

Here is my own documentation based on http://ask.metafilter.com/67634/How-can-I-set-up-Bugzilla-to-receive-bugs-via-email that could serve as a basis if there is nothing else. It applies to Debian Lenny.

- Use checksetup.pl to find missing Perl modules
- Install procmail
- Create a user that will receive emails (should be the same as configured in Bugzilla "mailfrom"
  For example: useradd -m -G www-data bugzilla-daemon
  -m  --> create homedir (so that Maildir can be created)
  -G  --> group of the apache-user (so that user has rights to call the email_in.pl script)
- Create /home/bugzilla-daemon/.procmailrc
  LOGFILE=/home/bugzilla-daemon/procmail_log

  :0
  * ^To:.*[e-mail]
  | /var/www/bugzilla/email_in.pl -vvv

  logfile should be commented out and "-vvv" be removed if everything works fine
- chown bugzilla-daemon.bugzilla-daemon /home/bugzilla-daemon/.procmailrc

Comment 11

[Larsen]

It should also be documented that signatures should be separated by "-- " (with space!) so that it gets removed automatically.