issue2550757: one bug raised by issue fixed. Patch created by

W. Trevor King (wking) for documentation of mailgw applied by
John Rouillard.

Author: rouilj

CHANGES.txt

@@ -39,6 +39,9 @@ Fixed:
 - issue2550748: Crash when creating new issues with non-existing
   multilink values (in classic template). Applied patch so it
   now errors the same way as an update does. (applied by John Rouillard)
+- issue2550757: one bug raised by issue fixed. Patch created by
+  W. Trevor King (wking) for documentation of mailgw applied by 
+  John Rouillard.
 
 2016-01-11: 1.5.1
 

doc/user_guide.txt

@@ -402,12 +402,20 @@ Subject-line information
 
 The subject line of the incoming message is examined to find one of:
 
-1. the item that the message is responding to,
-2. the type of item the message should create, or
-3. we default the item class and try some trickiness
+1. a case insentive ``help``,
+2. a match for ``-- key <OneTimeKey>``,
+3. the item that the message is responding to,
+4. the type of item the message should create, or
+5. we default the item class and try some trickiness.
+
+If the subject is ``help`` (case insensitive), the gateway responds
+with an explaination of the interface.
+
+If a one-time key is found, we're processing an in-progress
+registration confirmation.
 
 If the subject line contains a prefix in ``[square brackets]`` then
-we're looking at case 1 or 2 above. Any "re:" or "fwd:" prefixes are
+we're looking at case 3 or 4 above. Any "re:" or "fwd:" prefixes are
 stripped off the subject line before we start looking for real
 information.
 
@@ -421,7 +429,7 @@ item of that class with its "messages" property initialized to contain
 the new "msg" item and its "files" property initialized to contain any
 new "file" items.
 
-The third case above - where no ``[information]`` is provided, the
+The fifth case above - where no ``[information]`` is provided, the
 tracker's ``MAIL_DEFAULT_CLASS`` configuration variable defines what
 class of item the message relates to. We try to match the subject line
 to an existing item of the default class, and if there's a match, the

roundup/mailgw.py

@@ -31,14 +31,6 @@ class node. Any parts of other types are each stored in separate files
    special handling of the first text part) if unpack_rfc822 is set in
    the mailgw config section.
 
-Summary
--------
-The "summary" property on message nodes is taken from the first non-quoting
-section in the message body. The message body is divided into sections by
-blank lines. Sections where the second and all subsequent lines begin with
-a ">" or "|" character are considered "quoting sections". The first line of
-the first non-quoting section becomes the summary of the message.
-
 Addresses
 ---------
 All of the addresses in the To: and Cc: headers of the incoming message are
@@ -54,10 +46,26 @@ class node. Any parts of other types are each stored in separate files
 
 Actions
 -------
-The subject line of the incoming message is examined to determine whether
-the message is an attempt to create a new item or to discuss an existing
-item. A designator enclosed in square brackets is sought as the first thing
-on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
+The subject line of the incoming message is examined to determine
+whether the message is an attempt to create a new item, discuss an
+existing item, or execute some other command.
+
+If the subject consists of one of the following (case insensitive),
+the corresponding action is taken:
+
+help
+  Respond with an explanation of this interface.
+
+If the subject contains the following, the corresponding action is
+taken:
+
+-- key <OneTimeKey>
+  Complete an in-progress user registration.
+
+If the email is not a command, it is either a new item or a message
+associated with an existing item.  A designator enclosed in square
+brackets is sought as the first thing on the subject line (after
+skipping any "Fwd:" or "Re:" prefixes).
 
 If an item designator (class name and id number) is found there, the newly
 created "msg" node is added to the "messages" property for that item, and
@@ -68,6 +76,14 @@ class node. Any parts of other types are each stored in separate files
 "msg" node and its "files" property initialized to contain any new "file"
 nodes.
 
+Summary
+-------
+The "summary" property on message nodes is taken from the first non-quoting
+section in the message body. The message body is divided into sections by
+blank lines. Sections where the second and all subsequent lines begin with
+a ">" or "|" character are considered "quoting sections". The first line of
+the first non-quoting section becomes the summary of the message.
+
 Triggers
 --------
 Both cases may trigger detectors (in the first case we are calling the