[PATCH 7 of 8] e-mail: add documentation about configuration settings to ini files

[Mads Kiilerich]

On 07/22/2015 09:50 PM, Thomas De Schampheleire wrote:
> # HG changeset patch
> # User Thomas De Schampheleire <thomas.de.schampheleire at gmail.com>
> # Date 1437061235 -7200
> #      Thu Jul 16 17:40:35 2015 +0200
> # Node ID c024931198851143a30a4e218bbc9d7ff70927e1
> # Parent  f7b9681ad240d1ddd831f117b312cf24f67e33c5
> e-mail: add documentation about configuration settings to ini files

Nice and also quite verbose help. Should some of it perhaps be in the 
documentation instead? I don't know.

> diff --git a/development.ini b/development.ini
> --- a/development.ini
> +++ b/development.ini
> @@ -16,9 +16,22 @@ debug = true
>   pdebug = false
>   
>   ################################################################################
> -## Uncomment and replace with the address which should receive                ##
> -## any error reports after application crash                                  ##
> -## Additionally those settings will be used by Kallithea mailing system       ##
> +## E-mail settings                                                            ##
> +##                                                                            ##
> +## E-mail is sent in two broad categories:                                    ##
> +## - Error e-mails: In case an exception occurs in Kallithea, an e-mail with  ##
> +##   details about the exception is sent by Paste to the address specified    ##
> +##   in 'email_to', from the address specified in 'error_email_from'.         ##

IIRC, that will only happen if paste error mails are enabled ... and 
"often" they are not. A bit more context would perhaps be nice.

> +## - Application e-mails: Kallithea itself sends e-mail to the administrator  ##
> +##   specified in 'email_to' for notifications like new user registration and ##
> +##   to individual users for notifications about new code comments, review    ##
> +##   invitations, ... These e-mails originate from the address specified in   ##
> +##   'app_email_from'.                                                        ##

The application mails are more common and perhaps more important and 
should perhaps be first. And mails to users should perhaps also be 
mentioned before admin mails.

The descriptions and examples still kind of leave it undefined whether 
it just is the email address or if it could/should be in 'User Name 
<user at example.com>" format.

> +##   If desired, the subject of these application e-mails can be prefixed     ##
> +##   with the text specified in 'email_prefix'.                               ##
> +##                                                                            ##
> +## Note: your SMTP server may require 'app_email_from'/'error_email_from' to  ##
> +## be a valid, existing addresses.                                            ##

I still think it is a better advice to always use real addresses. Any 
mail server might have requirements to the originating email address.

/Mads