2 files changed, 123 insertions, 1 deletions

diff --git a/src/mailman/commands/cli_withlist.py b/src/mailman/commands/cli_withlist.py
index 9cfebd2bc..5aa5a5ec8 100644
--- a/src/mailman/commands/cli_withlist.py
+++ b/src/mailman/commands/cli_withlist.py
@@ -97,7 +97,7 @@ class Withlist:
         # Detailed help wanted?
         if args.details:
             self._details()
-            sys.exit(0)
+            return
         # Interactive is the default unless --run was given.
         if args.interactive is None:
             interactive = (args.run is None)
diff --git a/src/mailman/commands/docs/withlist.txt b/src/mailman/commands/docs/withlist.txt
new file mode 100644
index 000000000..f85607ab9
--- /dev/null
+++ b/src/mailman/commands/docs/withlist.txt
@@ -0,0 +1,122 @@
+==========================
+Operating on mailing lists
+==========================
+
+The 'withlist' command is a pretty powerful way to operate on mailing lists
+from the command line.  This command allows you to interact with a list at a
+Python prompt, or process one or more mailing lists through custom made Python
+functions.
+
+XXX Test the interactive operation of withlist
+
+
+Getting detailed help
+=====================
+
+Because withlist is so complex, you need to request detailed help.
+
+    >>> from mailman.commands.cli_withlist import Withlist
+    >>> command = Withlist()
+
+    >>> class FakeArgs:
+    ...     interactive = False
+    ...     run = None
+    ...     details = True
+    ...     listname = []
+
+    >>> class FakeParser:
+    ...     def error(self, message):
+    ...         print message
+    >>> command.parser = FakeParser()
+
+    >>> args = FakeArgs()
+    >>> command.process(args)
+    This script provides you with a general framework for interacting with a
+    mailing list.
+    ...
+
+
+Running a command
+=================
+
+By putting a Python function somewhere on your sys.path, you can have withlist
+call that function on a given mailing list.  The function takes a single
+argument, the mailing list.
+
+    >>> import os, sys
+    >>> old_path = sys.path[:]
+    >>> sys.path.insert(0, config.VAR_DIR)
+
+    >>> with open(os.path.join(config.VAR_DIR, 'showme.py'), 'w') as fp:
+    ...     print >> fp, """\
+    ... def showme(mailing_list):
+    ...     print "The list's name is", mailing_list.fqdn_listname
+    ...
+    ... def realname(mailing_list):
+    ...     print "The list's real name is", mailing_list.real_name
+    ... """
+
+If the name of the function is the same as the module, then you only need to
+name the function once.
+
+    >>> mlist = create_list('aardvark@example.com')
+    >>> args.details = False
+    >>> args.run = 'showme'
+    >>> args.listname = 'aardvark@example.com'
+    >>> command.process(args)
+    The list's name is aardvark@example.com
+
+The function's name can also be different than the modules name.  In that
+case, just give the full module path name to the function you want to call.
+
+    >>> args.run = 'showme.realname'
+    >>> command.process(args)
+    The list's real name is Aardvark
+
+
+Multiple lists
+==============
+
+You can run a command over more than one list by using a regular expression in
+the LISTNAME argument.  To indicate a regular expression is used, the string
+must start with a caret.
+
+    >>> mlist_2 = create_list('badger@example.com')
+    >>> mlist_3 = create_list('badboys@example.com')
+
+    >>> args.listname = '^.*example.com'
+    >>> command.process(args)
+    The list's real name is Aardvark
+    The list's real name is Badger
+    The list's real name is Badboys
+
+    >>> args.listname = '^bad.*'
+    >>> command.process(args)
+    The list's real name is Badger
+    The list's real name is Badboys
+
+    >>> args.listname = '^foo'
+    >>> command.process(args)
+
+
+Error handling
+==============
+
+You get an error if you try to run a function over a non-existent mailing
+list.
+
+    >>> args.listname = 'mystery@example.com'
+    >>> command.process(args)
+    No such list: mystery@example.com
+
+You also get an error if no mailing list is named.
+
+    >>> args.listname = None
+    >>> command.process(args)
+    --run requires a mailing list name
+
+
+Clean up
+========
+
+    >>> sys.path = old_path