11 files changed, 266 insertions, 32 deletions

diff --git a/src/mailman/commands/docs/echo.rst b/src/mailman/commands/docs/echo.rst
index ced483ea8..db5161e1e 100644
--- a/src/mailman/commands/docs/echo.rst
+++ b/src/mailman/commands/docs/echo.rst
@@ -1,3 +1,4 @@
+==================
 The 'echo' command
 ==================
 
@@ -5,12 +6,12 @@ The mail command 'echo' simply replies with the original command and arguments
 to the sender.
 
     >>> command = config.commands['echo']
-    >>> command.name
-    'echo'
-    >>> command.argument_description
-    '[args]'
+    >>> print command.name
+    echo
+    >>> print command.argument_description
+    [args]
     >>> print command.description
-    Echo an acknowledgement.  Arguments are return unchanged.
+    Echo back your arguments.
 
 The original message is ignored, but the results receive the echoed command.
 ::
diff --git a/src/mailman/commands/docs/end.rst b/src/mailman/commands/docs/end.rst
index a11bea095..accf91b90 100644
--- a/src/mailman/commands/docs/end.rst
+++ b/src/mailman/commands/docs/end.rst
@@ -1,3 +1,4 @@
+=================
 The 'end' command
 =================
 
@@ -5,8 +6,8 @@ The mail command processor recognized an 'end' command which tells it to stop
 processing email messages.
 
     >>> command = config.commands['end']
-    >>> command.name
-    'end'
+    >>> print command.name
+    end
     >>> print command.description
     Stop processing commands.
 
@@ -29,7 +30,7 @@ The 'stop' command is a synonym for 'end'.
     >>> print command.name
     stop
     >>> print command.description
-    Stop processing commands.
+    An alias for 'end'.
     >>> command.argument_description
     ''
     >>> print command.process(mlist, Message(), {}, (), None)
diff --git a/src/mailman/commands/docs/help.rst b/src/mailman/commands/docs/help.rst
new file mode 100644
index 000000000..a12a4008f
--- /dev/null
+++ b/src/mailman/commands/docs/help.rst
@@ -0,0 +1,71 @@
+==================
+Email command help
+==================
+
+You can get some help about the various email commands that are available by
+sending the word `help` to a mailing list's -request address.
+
+    >>> mlist = create_list('test@example.com')
+    >>> from mailman.commands.eml_help import Help
+    >>> help = Help()
+    >>> print help.name
+    help
+    >>> print help.description
+    Get help about available email commands.
+    >>> print help.argument_description
+    [command]
+
+With no arguments, `help` provides a list of the available commands and a
+short description of each of them.
+::
+
+    >>> from mailman.runners.command import Results
+    >>> results = Results()
+
+    >>> from mailman.email.message import Message
+    >>> print help.process(mlist, Message(), {}, (), results)
+    ContinueProcessing.yes
+    >>> print unicode(results)
+    The results of your email command are provided below.
+    <BLANKLINE>
+    confirm     - Confirm a subscription request.
+    echo        - Echo back your arguments.
+    end         - Stop processing commands.
+    help        - Get help about available email commands.
+    join        - Join this mailing list.
+    leave       - Leave this mailing list.
+    stop        - An alias for 'end'.
+    subscribe   - An alias for 'join'.
+    unsubscribe - An alias for 'leave'.
+    <BLANKLINE>
+
+With an argument, you can get more detailed help about a specific command.
+
+    >>> results = Results()
+    >>> print help.process(mlist, Message(), {}, ('help',), results)
+    ContinueProcessing.yes
+    >>> print unicode(results)
+    The results of your email command are provided below.
+    <BLANKLINE>
+    help [command]
+    Get help about available email commands.
+    <BLANKLINE>
+    
+Some commands have even more detailed help.
+
+    >>> results = Results()
+    >>> print help.process(mlist, Message(), {}, ('join',), results)
+    ContinueProcessing.yes
+    >>> print unicode(results)
+    The results of your email command are provided below.
+    <BLANKLINE>
+    join [digest=<no|mime|plain>]
+    Join this mailing list.
+    <BLANKLINE>
+    You will be asked to confirm your subscription request and you may be
+    issued a provisional password.
+    <BLANKLINE>
+    By using the 'digest' option, you can specify whether you want digest
+    delivery or not.  If not specified, the mailing list's default delivery
+    mode will be used.
+    <BLANKLINE>
diff --git a/src/mailman/commands/docs/membership.rst b/src/mailman/commands/docs/membership.rst
index d3643c2b1..7f4de8570 100644
--- a/src/mailman/commands/docs/membership.rst
+++ b/src/mailman/commands/docs/membership.rst
@@ -14,20 +14,17 @@ The mail command ``join`` subscribes an email address to the mailing list.
 ``subscribe`` is an alias for ``join``.
 
     >>> from mailman.commands.eml_membership import Join
+    >>> from mailman.utilities.string import wrap
     >>> join = Join()
     >>> print join.name
     join
-    >>> print join.description
-    Join this mailing list.  You will be asked to confirm your subscription
-    request and you may be issued a provisional password.
+    >>> print wrap(join.description)
+    You will be asked to confirm your subscription request and you may be
+    issued a provisional password.
     <BLANKLINE>
     By using the 'digest' option, you can specify whether you want digest
-    delivery or not.  If not specified, the mailing list's default will be
-    used.  You can also subscribe an alternative address by using the
-    'address' option.  For example:
-    <BLANKLINE>
-        join address=myotheraddress@example.com
-    <BLANKLINE>
+    delivery or not.  If not specified, the mailing list's default
+    delivery mode will be used.
     >>> print join.argument_description
     [digest=<no|mime|plain>]
 
@@ -232,7 +229,9 @@ list.  ``unsubscribe`` is an alias for ``leave``.
     >>> print leave.name
     leave
     >>> print leave.description
-    Leave this mailing list.  You will be asked to confirm your request.
+    Leave this mailing list.
+    <BLANKLINE>
+    You may be asked to confirm your request.
 
 Anne is a member of the ``baker@example.com`` mailing list, when she decides
 to leave it.  She sends a message to the ``-leave`` address for the list and
diff --git a/src/mailman/commands/eml_confirm.py b/src/mailman/commands/eml_confirm.py
index 2461192ed..55619a503 100644
--- a/src/mailman/commands/eml_confirm.py
+++ b/src/mailman/commands/eml_confirm.py
@@ -40,8 +40,9 @@ class Confirm:
     implements(IEmailCommand)
 
     name = 'confirm'
-    argument_description = ''
-    description = ''
+    argument_description = 'token'
+    description = _('Confirm a subscription request.')
+    short_description = description
 
     def process(self, mlist, msg, msgdata, arguments, results):
         """See `IEmailCommand`."""
diff --git a/src/mailman/commands/eml_echo.py b/src/mailman/commands/eml_echo.py
index 4686d0e4d..06d5ee5e7 100644
--- a/src/mailman/commands/eml_echo.py
+++ b/src/mailman/commands/eml_echo.py
@@ -17,6 +17,8 @@
 
 """The email command 'echo'."""
 
+from __future__ import absolute_import, print_function, unicode_literals
+
 __metaclass__ = type
 __all__ = [
     'Echo',
@@ -39,10 +41,10 @@ class Echo:
 
     name = 'echo'
     argument_description = '[args]'
-    description = _(
-        'Echo an acknowledgement.  Arguments are return unchanged.')
+    description = _('Echo back your arguments.')
+    short_description = description
 
     def process(self, mlist, msg, msgdata, arguments, results):
         """See `IEmailCommand`."""
-        print >> results, 'echo', SPACE.join(arguments)
+        print('echo', SPACE.join(arguments), file=results)
         return ContinueProcessing.yes
diff --git a/src/mailman/commands/eml_end.py b/src/mailman/commands/eml_end.py
index 56fd705a2..3cd70813c 100644
--- a/src/mailman/commands/eml_end.py
+++ b/src/mailman/commands/eml_end.py
@@ -38,6 +38,7 @@ class End:
     name = 'end'
     argument_description = ''
     description = _('Stop processing commands.')
+    short_description = description
 
     def process(self, mlist, msg, msgdata, arguments, results):
         """See `IEmailCommand`."""
@@ -49,3 +50,5 @@ class Stop(End):
     """The email 'stop' command (an alias for 'end')."""
 
     name = 'stop'
+    description = _("An alias for 'end'.")
+    short_description = description
diff --git a/src/mailman/commands/eml_help.py b/src/mailman/commands/eml_help.py
new file mode 100644
index 000000000..6fddb4ef3
--- /dev/null
+++ b/src/mailman/commands/eml_help.py
@@ -0,0 +1,81 @@
+# Copyright (C) 2012 by the Free Software Foundation, Inc.
+#
+# This file is part of GNU Mailman.
+#
+# GNU Mailman is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Mailman.  If not, see <http://www.gnu.org/licenses/>.
+
+"""The email command 'help'."""
+
+from __future__ import absolute_import, print_function, unicode_literals
+
+__metaclass__ = type
+__all__ = [
+    'Help',
+    ]
+
+
+from zope.interface import implements
+
+from mailman.config import config
+from mailman.core.i18n import _
+from mailman.interfaces.command import ContinueProcessing, IEmailCommand
+from mailman.utilities.string import wrap
+
+
+SPACE = ' '
+
+
+
+class Help:
+    """The email 'help' command."""
+
+    implements(IEmailCommand)
+
+    name = 'help'
+    argument_description = '[command]'
+    description = _('Get help about available email commands.')
+    short_description = description
+
+    def process(self, mlist, msg, msgdata, arguments, results):
+        """See `IEmailCommand`."""
+        # With no argument, print the command and a short description, which
+        # is contained in the short_description attribute.
+        if len(arguments) == 0:
+            length = max(len(command) for command in config.commands)
+            format = '{{0: <{0}s}} - {{1}}'.format(length)
+            for command_name in sorted(config.commands):
+                command = config.commands[command_name]
+                short_description = getattr(
+                    command, 'short_description', _('n/a'))
+                print(format.format(command.name, short_description), 
+                      file=results)
+            return ContinueProcessing.yes
+        elif len(arguments) == 1:
+            command_name = arguments[0]
+            command = config.commands.get(command_name)
+            if command is None:
+                print(_('$self.name: no such command: $command_name'), 
+                      file=results)
+                return ContinueProcessing.no
+            print('{0} {1}'.format(command.name, command.argument_description),
+                  file=results)
+            print(command.short_description, file=results)
+            if command.short_description != command.description:
+                print(wrap(command.description), file=results)
+            return ContinueProcessing.yes
+        else:
+            printable_arguments = SPACE.join(arguments)
+            print(_('$self.name: too many arguments: $printable_arguments'),
+                  file=results)
+            return ContinueProcessing.no
diff --git a/src/mailman/commands/eml_membership.py b/src/mailman/commands/eml_membership.py
index b4f24b514..386316eb9 100644
--- a/src/mailman/commands/eml_membership.py
+++ b/src/mailman/commands/eml_membership.py
@@ -50,16 +50,14 @@ class Join:
     # XXX 2012-02-29 BAW: DeliveryMode.summary is not yet supported.
     argument_description = '[digest=<no|mime|plain>]'
     description = _("""\
-Join this mailing list.  You will be asked to confirm your subscription
-request and you may be issued a provisional password.
+You will be asked to confirm your subscription request and you may be issued a
+provisional password.
 
 By using the 'digest' option, you can specify whether you want digest delivery
-or not.  If not specified, the mailing list's default will be used.  You can
-also subscribe an alternative address by using the 'address' option.  For
-example:
-
-    join address=myotheraddress@example.com
+or not.  If not specified, the mailing list's default delivery mode will be
+used.
 """)
+    short_description = _('Join this mailing list.')
 
     def process(self, mlist, msg, msgdata, arguments, results):
         """See `IEmailCommand`."""
@@ -128,6 +126,8 @@ class Subscribe(Join):
     """The email 'subscribe' command (an alias for 'join')."""
 
     name = 'subscribe'
+    description = _("An alias for 'join'.")
+    short_description = description
 
 
 
@@ -138,8 +138,10 @@ class Leave:
 
     name = 'leave'
     argument_description = ''
-    description = _(
-        'Leave this mailing list.  You will be asked to confirm your request.')
+    description = _("""Leave this mailing list.  
+
+You may be asked to confirm your request.""")
+    short_description = _('Leave this mailing list.')
 
     def process(self, mlist, msg, msgdata, arguments, results):
         """See `IEmailCommand`."""
@@ -184,3 +186,5 @@ class Unsubscribe(Leave):
     """The email 'unsubscribe' command (an alias for 'leave')."""
 
     name = 'unsubscribe'
+    description = _("An alias for 'leave'.")
+    short_description = description
diff --git a/src/mailman/commands/tests/test_help.py b/src/mailman/commands/tests/test_help.py
new file mode 100644
index 000000000..3892aead5
--- /dev/null
+++ b/src/mailman/commands/tests/test_help.py
@@ -0,0 +1,70 @@
+# Copyright (C) 2012 by the Free Software Foundation, Inc.
+#
+# This file is part of GNU Mailman.
+#
+# GNU Mailman is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Mailman.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Additional tests for the `help` email command."""
+
+from __future__ import absolute_import, print_function, unicode_literals
+
+__metaclass__ = type
+__all__ = [
+    ]
+
+
+import unittest
+
+from mailman.app.lifecycle import create_list
+from mailman.commands.eml_help import Help
+from mailman.email.message import Message
+from mailman.interfaces.command import ContinueProcessing
+from mailman.runners.command import Results
+from mailman.testing.layers import ConfigLayer
+
+
+
+class TestHelp(unittest.TestCase):
+    """Test email help."""
+
+    layer = ConfigLayer
+
+    def setUp(self):
+        self._mlist = create_list('test@example.com')
+        self._help = Help()
+
+    def test_too_many_arguments(self):
+        # Error message when too many help arguments are given.
+        results = Results()
+        status = self._help.process(self._mlist, Message(), {}, 
+                                    ('more', 'than', 'one'),
+                                    results)
+        self.assertEqual(status, ContinueProcessing.no)
+        self.assertEqual(unicode(results), """\
+The results of your email command are provided below.
+
+help: too many arguments: more than one
+""")
+
+    def test_no_such_command(self):
+        # Error message when asking for help on an existent command.
+        results = Results()
+        status = self._help.process(self._mlist, Message(), {}, 
+                                    ('doesnotexist',), results)
+        self.assertEqual(status, ContinueProcessing.no)
+        self.assertEqual(unicode(results), """\
+The results of your email command are provided below.
+
+help: no such command: doesnotexist
+""")
diff --git a/src/mailman/docs/NEWS.rst b/src/mailman/docs/NEWS.rst
index 2bad038f7..368483c05 100644
--- a/src/mailman/docs/NEWS.rst
+++ b/src/mailman/docs/NEWS.rst
@@ -53,6 +53,7 @@ Commands
  * The `join` email command no longer accepts an `address=` argument.  Its
    `digest=` argument now accepts the following values: `no` (for regular
    delivery), `mime`, or `plain`.
+ * Added a `help` email command.
 
 Bug fixes
 ---------