More documentation updates

1 files changed, 38 insertions, 34 deletions

diff --git a/src/mailman/pipeline/docs/subject-munging.txt b/src/mailman/pipeline/docs/subject-munging.txt
index 20f3b04ed..e7a6553ce 100644
--- a/src/mailman/pipeline/docs/subject-munging.txt
+++ b/src/mailman/pipeline/docs/subject-munging.txt
@@ -2,7 +2,7 @@
 Subject munging
 ===============
 
-Messages that flow through the global pipeline get their headers 'cooked',
+Messages that flow through the global pipeline get their headers *cooked*,
 which basically means that their headers go through several mostly unrelated
 transformations.  Some headers get added, others get changed.  Some of these
 changes depend on mailing list settings and others depend on how the message
@@ -14,10 +14,11 @@ is getting sent through the system.  We'll take things one-by-one.
 Inserting a prefix
 ==================
 
-Another thing CookHeaders does is 'munge' the Subject header by inserting the
-subject prefix for the list at the front.  If there's no subject header in the
-original message, Mailman uses a canned default.  In order to do subject
-munging, a mailing list must have a preferred language.
+Another thing header cooking does is *munge* the ``Subject`` header by
+inserting the subject prefix for the list at the front.  If there's no subject
+header in the original message, Mailman uses a canned default.  In order to do
+subject munging, a mailing list must have a preferred language.
+::
 
     >>> mlist.subject_prefix = '[XTest] '
     >>> mlist.preferred_language = 'en'
@@ -32,16 +33,16 @@ munging, a mailing list must have a preferred language.
     >>> process(mlist, msg, msgdata)
 
 The original subject header is stored in the message metadata.  We must print
-the new Subject header because it gets converted from a string to an
-email.header.Header instance which has an unhelpful repr.
+the new ``Subject`` header because it gets converted from a string to an
+``email.header.Header`` instance which has an unhelpful ``repr``.
 
     >>> msgdata['origsubj']
     u''
     >>> print msg['subject']
     [XTest] (no subject)
 
-If the original message had a Subject header, then the prefix is inserted at
-the beginning of the header's value.
+If the original message had a ``Subject`` header, then the prefix is inserted
+at the beginning of the header's value.
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
@@ -56,7 +57,7 @@ the beginning of the header's value.
     >>> print msg['subject']
     [XTest] Something important
 
-Subject headers are not munged for digest messages.
+``Subject`` headers are not munged for digest messages.
     
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
@@ -68,7 +69,7 @@ Subject headers are not munged for digest messages.
     >>> print msg['subject']
     Something important
 
-Nor are they munged for 'fast tracked' messages, which are generally defined
+Nor are they munged for *fast tracked* messages, which are generally defined
 as messages that Mailman crafts internally.
 
     >>> msg = message_from_string("""\
@@ -81,9 +82,9 @@ as messages that Mailman crafts internally.
     >>> print msg['subject']
     Something important
 
-If a Subject header already has a prefix, usually following a Re: marker,
-another one will not be added but the prefix will be moved to the front of the
-header text.
+If a ``Subject`` header already has a prefix, usually following a ``Re:``
+marker, another one will not be added but the prefix will be moved to the
+front of the header text.
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.com
@@ -95,8 +96,8 @@ header text.
     >>> print msg['subject']
     [XTest] Re: Something important
 
-If the Subjec header has a prefix at the front of the header text, that's
-where it will stay.  This is called 'new style' prefixing and is the only
+If the ``Subject`` header has a prefix at the front of the header text, that's
+where it will stay.  This is called *new style* prefixing and is the only
 option available in Mailman 3.
 
     >>> msg = message_from_string("""\
@@ -133,8 +134,8 @@ Prefix numbers
 ==============
 
 Subject prefixes support a placeholder for the numeric post id.  Every time a
-message is posted to the mailing list, a 'post id' gets incremented.  This is
-a purely sequential integer that increases monotonically.  By added a '%d'
+message is posted to the mailing list, a *post id* gets incremented.  This is
+a purely sequential integer that increases monotonically.  By added a ``%d``
 placeholder to the subject prefix, this post id can be included in the prefix.
 
     >>> mlist.subject_prefix = '[XTest %d] '
@@ -159,7 +160,7 @@ id.
     >>> print msg['subject']
     [XTest 456] Re: Something important
 
-If the Subject header had old style prefixing, the prefix is moved to the
+If the ``Subject`` header had old style prefixing, the prefix is moved to the
 front of the header text.
 
     >>> msg = message_from_string("""\
@@ -172,7 +173,7 @@ front of the header text.
 
 
 And of course, the proper thing is done when posting id numbers are included
-in the subject prefix, and the subject is encoded non-ascii.
+in the subject prefix, and the subject is encoded non-ASCII.
 
     >>> msg = message_from_string("""\
     ... Subject: =?iso-2022-jp?b?GyRCJWEhPCVrJV4lcxsoQg==?=
@@ -184,8 +185,8 @@ in the subject prefix, and the subject is encoded non-ascii.
     >>> unicode(msg['subject'])
     u'[XTest 456] \u30e1\u30fc\u30eb\u30de\u30f3'
 
-Even more fun is when the i18n Subject header already has a prefix, possibly
-with a different posting number.
+Even more fun is when the internationalized ``Subject`` header already has a
+prefix, possibly with a different posting number.
 
     >>> msg = message_from_string("""\
     ... Subject: [XTest 123] Re: =?iso-2022-jp?b?GyRCJWEhPCVrJV4lcxsoQg==?=
@@ -195,9 +196,10 @@ with a different posting number.
     >>> print msg['subject']
     [XTest 456] Re: =?iso-2022-jp?b?GyRCJWEhPCVrJV4lcxsoQg==?=
 
-# XXX This requires Python email patch #1681333 to succeed.
-#    >>> unicode(msg['subject'])
-#    u'[XTest 456] Re: \u30e1\u30fc\u30eb\u30de\u30f3'
+..
+ # XXX This requires Python email patch #1681333 to succeed.
+ #    >>> unicode(msg['subject'])
+ #    u'[XTest 456] Re: \u30e1\u30fc\u30eb\u30de\u30f3'
 
 As before, old style subject prefixes are re-ordered.
 
@@ -210,13 +212,14 @@ As before, old style subject prefixes are re-ordered.
     [XTest 456] Re:
       =?iso-2022-jp?b?GyRCJWEhPCVrJV4lcxsoQg==?=
 
-# XXX This requires Python email patch #1681333 to succeed.
-#    >>> unicode(msg['subject'])
-#    u'[XTest 456] Re: \u30e1\u30fc\u30eb\u30de\u30f3'
+..
+ # XXX This requires Python email patch #1681333 to succeed.
+ #    >>> unicode(msg['subject'])
+ #    u'[XTest 456] Re: \u30e1\u30fc\u30eb\u30de\u30f3'
 
 
 In this test case, we get an extra space between the prefix and the original
-subject.  It's because the original is 'crooked'.  Note that a Subject
+subject.  It's because the original is *crooked*.  Note that a ``Subject``
 starting with '\n ' is generated by some version of Eudora Japanese edition.
 
     >>> mlist.subject_prefix = '[XTest] '
@@ -238,8 +241,9 @@ And again, with an RFC 2047 encoded header.
     ... """)
     >>> process(mlist, msg, {})
 
-# XXX This one does not appear to work the same way as
-# test_subject_munging_prefix_crooked() in the old Python-based tests.  I need
-# to get Tokio to look at this.
-#    >>> print msg['subject']
-#    [XTest] =?iso-2022-jp?b?IBskQiVhITwlayVeJXMbKEI=?=
+..
+ # XXX This one does not appear to work the same way as
+ # test_subject_munging_prefix_crooked() in the old Python-based tests.  I need
+ # to get Tokio to look at this.
+ #    >>> print msg['subject']
+ #    [XTest] =?iso-2022-jp?b?IBskQiVhITwlayVeJXMbKEI=?=