More documentation improvements.

7 files changed, 76 insertions, 61 deletions

diff --git a/src/mailman/pipeline/docs/acknowledge.txt b/src/mailman/pipeline/docs/acknowledge.txt
index f8e9d9d87..5e4240626 100644
--- a/src/mailman/pipeline/docs/acknowledge.txt
+++ b/src/mailman/pipeline/docs/acknowledge.txt
@@ -5,6 +5,7 @@ Message acknowledgment
 When a user posts a message to a mailing list, and that user has chosen to
 receive acknowledgments of their postings, Mailman will sent them such an
 acknowledgment.
+::
 
     >>> mlist = create_list('_xtest@example.com')
     >>> mlist.real_name = 'XTest'
@@ -19,6 +20,7 @@ acknowledgment.
     []
 
 Subscribe a user to the mailing list.
+::
 
     >>> from mailman.interfaces.usermanager import IUserManager
     >>> from zope.component import getUtility
@@ -35,6 +37,7 @@ Non-member posts
 ================
 
 Non-members can't get acknowledgments of their posts to the mailing list.
+::
 
     >>> msg = message_from_string("""\
     ... From: bperson@example.com
@@ -75,6 +78,7 @@ Unless the user has requested acknowledgments, they will not get one.
 Similarly if the original sender is specified in the message metadata, and
 that sender is a member but not one who has requested acknowledgments, none
 will be sent.
+::
 
     >>> user_2 = user_manager.create_user('dperson@example.com')
     >>> address_2 = list(user_2.addresses)[0]
diff --git a/src/mailman/pipeline/docs/after-delivery.txt b/src/mailman/pipeline/docs/after-delivery.txt
index eef153c7d..c3e393cf2 100644
--- a/src/mailman/pipeline/docs/after-delivery.txt
+++ b/src/mailman/pipeline/docs/after-delivery.txt
@@ -14,6 +14,7 @@ bookkeeping pieces of information are updated.
 
 Processing a message with this handler updates the last_post_time and post_id
 attributes.
+::
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
diff --git a/src/mailman/pipeline/docs/archives.txt b/src/mailman/pipeline/docs/archives.txt
index 51fd600bc..323d121e8 100644
--- a/src/mailman/pipeline/docs/archives.txt
+++ b/src/mailman/pipeline/docs/archives.txt
@@ -19,10 +19,10 @@ A helper function.
     ...         msg, msgdata = switchboard.dequeue(filebase)
     ...         switchboard.finish(filebase)
 
-The purpose of the ToArchive handler is to make a simple decision as to
-whether the message should get archived and if so, to drop the message in the
-archiving queue.  Really the most important things are to determine when a
-message should /not/ get archived.
+The purpose of this handler is to make a simple decision as to whether the
+message should get archived and if so, to drop the message in the archiving
+queue.  Really the most important things are to determine when a message
+should *not* get archived.
 
 For example, no digests should ever get archived.
 
@@ -46,8 +46,8 @@ won't be archived.
 
 There are two de-facto standards for a message to indicate that it does not
 want to be archived.  We've seen both in the wild so both are supported.  The
-X-No-Archive: header can be used to indicate that the message should not be
-archived.  Confusingly, this header's value is actually ignored.
+``X-No-Archive:`` header can be used to indicate that the message should not
+be archived.  Confusingly, this header's value is actually ignored.
 
     >>> mlist.archive = True
     >>> msg = message_from_string("""\
@@ -60,7 +60,7 @@ archived.  Confusingly, this header's value is actually ignored.
     >>> switchboard.files
     []
 
-Even a 'no' value will stop the archiving of the message.
+Even a ``no`` value will stop the archiving of the message.
 
     >>> msg = message_from_string("""\
     ... Subject: A sample message
@@ -72,8 +72,8 @@ Even a 'no' value will stop the archiving of the message.
     >>> switchboard.files
     []
 
-Another header that's been observed is the X-Archive: header.  Here, the
-header's case folded value must be 'no' in order to prevent archiving.
+Another header that's been observed is the ``X-Archive:`` header.  Here, the
+header's case folded value must be ``no`` in order to prevent archiving.
 
     >>> msg = message_from_string("""\
     ... Subject: A sample message
@@ -85,7 +85,7 @@ header's case folded value must be 'no' in order to prevent archiving.
     >>> switchboard.files
     []
 
-But if the value is 'yes', then the message will be archived.
+But if the value is ``yes``, then the message will be archived.
 
     >>> msg = message_from_string("""\
     ... Subject: A sample message
diff --git a/src/mailman/pipeline/docs/avoid-duplicates.txt b/src/mailman/pipeline/docs/avoid-duplicates.txt
index 22fc85207..bd753f9e9 100644
--- a/src/mailman/pipeline/docs/avoid-duplicates.txt
+++ b/src/mailman/pipeline/docs/avoid-duplicates.txt
@@ -2,14 +2,14 @@
 Avoid duplicates
 ================
 
-The AvoidDuplicates handler module implements several strategies to try to
-reduce the reception of duplicate messages.  It does this by removing certain
-recipients from the list of recipients that earlier handler modules
-(e.g. CalcRecips) calculates.
+This handler implements several strategies to reduce the reception of
+duplicate messages.  It does this by removing certain recipients from the list
+of recipients calculated earlier.
 
     >>> mlist = create_list('_xtest@example.com')
 
 Create some members we're going to use.
+::
 
     >>> from mailman.interfaces.usermanager import IUserManager
     >>> from zope.component import getUtility
@@ -31,6 +31,7 @@ Short circuiting
 ================
 
 The module short-circuits if there are no recipients.
+::
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
@@ -57,9 +58,9 @@ Suppressing the list copy
 
 Members can elect not to receive a list copy of any message on which they are
 explicitly named as a recipient.  This is done by setting their
-receive_list_copy preference to False.  However, if they aren't mentioned in
-one of the recipient headers (i.e. To, CC, Resent-To, or Resent-CC), then they
-will get a list copy.
+``receive_list_copy`` preference to ``False``.  However, if they aren't
+mentioned in one of the recipient headers (i.e. ``To``, ``CC``, ``Resent-To``,
+or ``Resent-CC``), then they will get a list copy.
 
     >>> member_a.preferences.receive_list_copy = False
     >>> msg = message_from_string("""\
@@ -77,7 +78,7 @@ will get a list copy.
     Something of great import.
     <BLANKLINE>
 
-If they're mentioned on the CC line, they won't get a list copy.
+If they're mentioned on the ``CC`` line, they won't get a list copy.
 
     >>> msg = message_from_string("""\
     ... From: Claire Person <cperson@example.com>
@@ -96,8 +97,8 @@ If they're mentioned on the CC line, they won't get a list copy.
     Something of great import.
     <BLANKLINE>
 
-But if they're mentioned on the CC line and have receive_list_copy set to True
-(the default), then they still get a list copy.
+But if they're mentioned on the ``CC`` line and have ``receive_list_copy`` set
+to ``True`` (the default), then they still get a list copy.
 
     >>> msg = message_from_string("""\
     ... From: Claire Person <cperson@example.com>
@@ -116,7 +117,7 @@ But if they're mentioned on the CC line and have receive_list_copy set to True
     Something of great import.
     <BLANKLINE>
 
-Other headers checked for recipients include the To...
+Other headers checked for recipients include the ``To``...
 
     >>> msg = message_from_string("""\
     ... From: Claire Person <cperson@example.com>
@@ -135,7 +136,7 @@ Other headers checked for recipients include the To...
     Something of great import.
     <BLANKLINE>
 
-...Resent-To...
+... ``Resent-To`` ...
 
     >>> msg = message_from_string("""\
     ... From: Claire Person <cperson@example.com>
@@ -154,7 +155,7 @@ Other headers checked for recipients include the To...
     Something of great import.
     <BLANKLINE>
 
-...and Resent-CC headers.
+...and ``Resent-CC`` headers.
 
     >>> msg = message_from_string("""\
     ... From: Claire Person <cperson@example.com>
diff --git a/src/mailman/pipeline/docs/calc-recips.txt b/src/mailman/pipeline/docs/calc-recips.txt
index 1b1903bf8..27c2ba806 100644
--- a/src/mailman/pipeline/docs/calc-recips.txt
+++ b/src/mailman/pipeline/docs/calc-recips.txt
@@ -10,6 +10,7 @@ modules and depends on a host of factors.
 
 Recipients are calculate from the list members, so add a bunch of members to
 start out with.  First, create a bunch of addresses...
+::
 
     >>> from mailman.interfaces.usermanager import IUserManager
     >>> from zope.component import getUtility
@@ -46,6 +47,7 @@ Short-circuiting
 Sometimes, the list of recipients already exists in the message metadata.
 This can happen for example, when a message was previously delivered to some
 but not all of the recipients.
+::
 
     >>> msg = message_from_string("""\
     ... From: Xavier Person <xperson@example.com>
@@ -86,8 +88,8 @@ Members can elect not to receive a list copy of their own postings.
     [u'aperson@example.com', u'bperson@example.com']
 
 Members can also elect not to receive a list copy of any message on which they
-are explicitly named as a recipient.  However, see the AvoidDuplicates handler
-for details.
+are explicitly named as a recipient.  However, see the `avoid duplicates`_
+handler for details.
 
 
 Digest recipients
@@ -103,3 +105,6 @@ XXX Test various urgent deliveries:
     * test_urgent_moderator()
     * test_urgent_admin()
     * test_urgent_reject()
+
+
+.. _`avoid duplicates`: avoid-duplicates.html
diff --git a/src/mailman/pipeline/docs/cleanse.txt b/src/mailman/pipeline/docs/cleanse.txt
index 155de0673..97fb9d3b4 100644
--- a/src/mailman/pipeline/docs/cleanse.txt
+++ b/src/mailman/pipeline/docs/cleanse.txt
@@ -8,12 +8,13 @@ headers can be used to fish for membership.
 
     >>> mlist = create_list('_xtest@example.com')
 
-Headers such as Approved, Approve, and Urgent are used to grant special
-pemissions to individual messages.  All may contain a password; the first two
-headers are used by list administrators to pre-approve a message normal held
-for approval.  The latter header is used to send a regular message to all
-members, regardless of whether they get digests or not.  Because all three
-headers contain passwords, they must be removed from any posted message.
+Headers such as ``Approved``, ``Approve``, and ``Urgent`` are used to grant
+special permissions to individual messages.  All may contain a password; the
+first two headers are used by list administrators to pre-approve a message
+normal held for approval.  The latter header is used to send a regular message
+to all members, regardless of whether they get digests or not.  Because all
+three headers contain passwords, they must be removed from any posted message.
+::
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
@@ -36,9 +37,9 @@ headers contain passwords, they must be removed from any posted message.
 
 Other headers can be used by list members to fish the list for membership, so
 we don't let them go through.  These are a mix of standard headers and custom
-headers supported by some mail readers.  For example, X-PMRC is supported by
-Pegasus mail.  I don't remember what program uses X-Confirm-Reading-To though
-(Some Microsoft product perhaps?).
+headers supported by some mail readers.  For example, ``X-PMRC`` is supported
+by Pegasus mail.  I don't remember what program uses ``X-Confirm-Reading-To``
+though (Some Microsoft product perhaps?).
 
     >>> msg = message_from_string("""\
     ... From: bperson@example.com
@@ -69,10 +70,11 @@ Anonymous lists
 Anonymous mailing lists also try to cleanse certain identifying headers from
 the original posting, so that it is at least a bit more difficult to determine
 who sent the message.  This isn't perfect though, for example, the body of the
-messages are never scrubbed (though that might not be a bad idea).  The From
-and Reply-To headers in the posted message are taken from list attributes.
+messages are never scrubbed (though that might not be a bad idea).  The
+``From`` and ``Reply-To`` headers in the posted message are taken from list
+attributes.
 
-Hotmail apparently sets X-Originating-Email.
+Hotmail apparently sets ``X-Originating-Email``.
 
     >>> mlist.anonymous_list = True
     >>> mlist.description = 'A Test Mailing List'
diff --git a/src/mailman/pipeline/docs/cook-headers.txt b/src/mailman/pipeline/docs/cook-headers.txt
index 5d078c342..834b140fa 100644
--- a/src/mailman/pipeline/docs/cook-headers.txt
+++ b/src/mailman/pipeline/docs/cook-headers.txt
@@ -17,8 +17,9 @@ is getting sent through the system.  We'll take things one-by-one.
 Saving the original sender
 ==========================
 
-Because the original sender headers may get deleted or changed, CookHeaders
+Because the original sender headers may get deleted or changed, this handler
 will place the sender in the message metadata for safe keeping.
+::
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
@@ -48,7 +49,7 @@ But if there was no original sender, then the empty string will be saved.
 Mailman version header
 ======================
 
-Mailman will also insert an X-Mailman-Version header...
+Mailman will also insert an ``X-Mailman-Version`` header...
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
@@ -76,8 +77,8 @@ Mailman will also insert an X-Mailman-Version header...
 Precedence header
 =================
 
-Mailman will insert a Precedence header, which is a de-facto standard for
-telling automatic reply software (e.g. vacation(1)) not to respond to this
+Mailman will insert a ``Precedence`` header, which is a de-facto standard for
+telling automatic reply software (e.g. ``vacation(1)``) not to respond to this
 message.
 
     >>> msg = message_from_string("""\
@@ -165,12 +166,12 @@ But normally, a list will include these headers.
     List-Id: <_xtest.example.com>
     List-Post: <mailto:_xtest@example.com>
     List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-join@example.com>
+        <mailto:_xtest-join@example.com>
     List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-leave@example.com>
+        <mailto:_xtest-leave@example.com>
     ---end---
 
-If the mailing list has a description, then it is included in the List-Id
+If the mailing list has a description, then it is included in the ``List-Id``
 header.
 
     >>> mlist.description = 'My test mailing list'
@@ -186,13 +187,14 @@ header.
     List-Id: My test mailing list <_xtest.example.com>
     List-Post: <mailto:_xtest@example.com>
     List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-join@example.com>
+        <mailto:_xtest-join@example.com>
     List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-leave@example.com>
+        <mailto:_xtest-leave@example.com>
     ---end---
 
 There are some circumstances when the list administrator wants to explicitly
-set the List-ID header.  Start by creating a new domain.
+set the ``List-ID`` header.  Start by creating a new domain.
+::
 
     >>> from mailman.interfaces.domain import IDomainManager
     >>> from zope.component import getUtility
@@ -211,7 +213,7 @@ set the List-ID header.  Start by creating a new domain.
     >>> mlist.host_name = 'example.com'
     >>> mlist.list_id = '_xtest.example.com'
 
-Any existing List-ID headers are removed from the original message.
+Any existing ``List-ID`` headers are removed from the original message.
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
@@ -235,14 +237,14 @@ Administrative messages crafted by Mailman will have a reduced set of headers.
     List-Help: <mailto:_xtest-request@example.com?subject=help>
     List-Id: My test mailing list <_xtest.example.com>
     List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-join@example.com>
+        <mailto:_xtest-join@example.com>
     List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-leave@example.com>
+        <mailto:_xtest-leave@example.com>
     X-List-Administrivia: yes
     ---end---
 
-With the normal set of List-* headers, it's still possible to suppress the
-List-Post header, which is reasonable for an announce only mailing list.
+With the normal set of ``List-*`` headers, it's still possible to suppress the
+``List-Post`` header, which is reasonable for an announce only mailing list.
 
     >>> mlist.include_list_post_header = False
     >>> msg = message_from_string("""\
@@ -256,13 +258,13 @@ List-Post header, which is reasonable for an announce only mailing list.
     List-Help: <mailto:_xtest-request@example.com?subject=help>
     List-Id: My test mailing list <_xtest.example.com>
     List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-join@example.com>
+        <mailto:_xtest-join@example.com>
     List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-leave@example.com>
+        <mailto:_xtest-leave@example.com>
     ---end---
 
 And if the list isn't being archived, it makes no sense to add the
-List-Archive header either.
+``List-Archive`` header either.
 
     >>> mlist.include_list_post_header = True
     >>> mlist.archive = False
@@ -277,16 +279,16 @@ List-Archive header either.
     List-Id: My test mailing list <_xtest.example.com>
     List-Post: <mailto:_xtest@example.com>
     List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-join@example.com>
+        <mailto:_xtest-join@example.com>
     List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-leave@example.com>
+        <mailto:_xtest-leave@example.com>
     ---end---
 
 
 Archived-At
 ===========
 
-RFC 5064 (draft) defines a new Archived-At header which contains the url to
+RFC 5064 (draft) defines a new ``Archived-At`` header which contains the url to
 the individual message in the archives.  The stock Pipermail archiver doesn't
 support this because the url can't be calculated until after the message is
 archived.  Because this is done by the archive runner, this information isn't
@@ -299,7 +301,7 @@ available to us now.
 Personalization
 ===============
 
-The To field normally contains the list posting address.  However when
+The ``To`` field normally contains the list posting address.  However when
 messages are fully personalized, that header will get overwritten with the
 address of the recipient.  The list's posting address will be added to one of
 the recipient headers so that users will be able to reply back to the list.
@@ -321,10 +323,10 @@ the recipient headers so that users will be able to reply back to the list.
     Cc: My test mailing list <_xtest@example.com>
     List-Id: My test mailing list <_xtest.example.com>
     List-Unsubscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-leave@example.com>
+        <mailto:_xtest-leave@example.com>
     List-Post: <mailto:_xtest@example.com>
     List-Help: <mailto:_xtest-request@example.com?subject=help>
     List-Subscribe: <http://lists.example.com/listinfo/_xtest@example.com>,
-    	<mailto:_xtest-join@example.com>
+        <mailto:_xtest-join@example.com>
     <BLANKLINE>
     <BLANKLINE>