diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/pipeline/docs/decorate.txt | 22 | ||||
| -rw-r--r-- | src/mailman/pipeline/docs/digests.txt | 1 | ||||
| -rw-r--r-- | src/mailman/pipeline/docs/file-recips.txt | 11 | ||||
| -rw-r--r-- | src/mailman/pipeline/docs/filtering.txt | 57 | ||||
| -rw-r--r-- | src/mailman/pipeline/docs/nntp.txt | 7 |
5 files changed, 54 insertions, 44 deletions
diff --git a/src/mailman/pipeline/docs/decorate.txt b/src/mailman/pipeline/docs/decorate.txt index e5b3db8d8..1c94cff1e 100644 --- a/src/mailman/pipeline/docs/decorate.txt +++ b/src/mailman/pipeline/docs/decorate.txt @@ -20,6 +20,7 @@ Short circuiting Digest messages get decorated during the digest creation phase so no extra decorations are added for digest messages. +:: >>> from mailman.pipeline.decorate import process >>> process(mlist, msg, dict(isdigest=True)) @@ -39,7 +40,7 @@ Decorating simple text messages =============================== Text messages that have no declared content type character set are by default, -encoded in us-ascii. When the mailing list's preferred language is 'en' +encoded in us-ascii. When the mailing list's preferred language is ``en`` (i.e. English), the character set of the mailing list and of the message will match. In this case, and when the header and footer have no interpolation placeholder variables, the message's payload will be prepended by the verbatim @@ -60,7 +61,7 @@ header, and appended with the verbatim footer. Mailman supports a number of interpolation variables, placeholders in the header and footer for information to be filled in with mailing list specific -data. An example of such information is the mailing list's "real name" (a +data. An example of such information is the mailing list's `real name` (a short descriptive name for the mailing list). >>> msg = message_from_string(msg_text) @@ -95,9 +96,9 @@ Handling RFC 3676 'format=flowed' parameters RFC 3676 describes a standard by which text/plain messages can marked by generating MUAs for better readability in compatible receiving MUAs. The -'format' parameter on the text/plain Content-Type header gives hints as to how -the receiving MUA may flow and delete trailing whitespace for better display -in a proportional font. +``format`` parameter on the text/plain ``Content-Type`` header gives hints as +to how the receiving MUA may flow and delete trailing whitespace for better +display in a proportional font. When Mailman sees text/plain messages with such RFC 3676 parameters, it preserves these parameters when it concatenates headers and footers to the @@ -130,6 +131,7 @@ When a message has no explicit character set, it is assumed to be us-ascii. However, if the mailing list's preferred language has a different character set, Mailman will still try to concatenate the header and footer, but it will convert the text to utf-8 and base-64 encode the message payload. +:: # 'ja' = Japanese; charset = 'euc-jp' >>> mlist.preferred_language = 'ja' @@ -205,9 +207,9 @@ cannot be simply concatenated into the payload because that will break the MIME structure of the message. Instead, the header and footer are attached as separate MIME subparts. -When the outerpart is multipart/mixed, the header and footer can have a -Content-Disposition of 'inline' so that MUAs can display these headers as if -they were simply concatenated. +When the outer part is ``multipart/mixed``, the header and footer can have a +``Content-Disposition`` of ``inline`` so that MUAs can display these headers +as if they were simply concatenated. >>> mlist.preferred_language = 'en' >>> mlist.msg_header = 'header' @@ -260,8 +262,8 @@ they were simply concatenated. Decorating other content types ============================== -Non-multipart non-text content types will get wrapped in a multipart/mixed so -that the header and footer can be added as attachments. +Non-multipart non-text content types will get wrapped in a ``multipart/mixed`` +so that the header and footer can be added as attachments. >>> msg = message_from_string("""\ ... From: aperson@example.org diff --git a/src/mailman/pipeline/docs/digests.txt b/src/mailman/pipeline/docs/digests.txt index 14d2a5636..b0a44ec5b 100644 --- a/src/mailman/pipeline/docs/digests.txt +++ b/src/mailman/pipeline/docs/digests.txt @@ -12,6 +12,7 @@ digests, although only two are currently supported: MIME digests and RFC 1153 This is a helper function used to iterate through all the accumulated digest messages, in the order in which they were posted. This makes it easier to update the tests when we switch to a different mailbox format. +:: >>> from mailman.testing.helpers import digest_mbox >>> from itertools import count diff --git a/src/mailman/pipeline/docs/file-recips.txt b/src/mailman/pipeline/docs/file-recips.txt index 3180df1fb..c7eeb9ce8 100644 --- a/src/mailman/pipeline/docs/file-recips.txt +++ b/src/mailman/pipeline/docs/file-recips.txt @@ -3,8 +3,8 @@ File recipients =============== Mailman can calculate the recipients for a message from a Sendmail-style -include file. This file must be called members.txt and it must live in the -list's data directory. +include file. This file must be called ``members.txt`` and it must live in +the list's data directory. >>> mlist = create_list('_xtest@example.com') @@ -14,6 +14,7 @@ Short circuiting If the message's metadata already has recipients, this handler immediately returns. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -37,7 +38,7 @@ Missing file ============ The include file must live inside the list's data directory, under the name -members.txt. If the file doesn't exist, the list of recipients will be +``members.txt``. If the file doesn't exist, the list of recipients will be empty. >>> import os @@ -58,6 +59,7 @@ Existing file If the file exists, it contains a list of addresses, one per line. These addresses are returned as the set of recipients. +:: >>> fp = open(file_path, 'w') >>> try: @@ -77,8 +79,9 @@ addresses are returned as the set of recipients. 'eperson@example.com', 'fperson@example.com', 'gperson@example.com'] However, if the sender of the original message is a member of the list and -their address is in the include file, the sender's address is /not/ included +their address is in the include file, the sender's address is *not* included in the recipients list. +:: >>> from mailman.interfaces.usermanager import IUserManager >>> from zope.component import getUtility diff --git a/src/mailman/pipeline/docs/filtering.txt b/src/mailman/pipeline/docs/filtering.txt index 241f282d9..5b54424e4 100644 --- a/src/mailman/pipeline/docs/filtering.txt +++ b/src/mailman/pipeline/docs/filtering.txt @@ -11,8 +11,8 @@ message. Several mailing list options control content filtering. First, the feature must be enabled, then there are two options that control which MIME types get filtered and which get passed. Finally, there is an option to control whether -text/html parts will get converted to plain text. Let's set up some defaults -for these variables, then we'll explain them in more detail below. +``text/html`` parts will get converted to plain text. Let's set up some +defaults for these variables, then we'll explain them in more detail below. >>> mlist.filter_content = True >>> mlist.filter_types = [] @@ -26,6 +26,7 @@ Filtering the outer content type A simple filtering setting will just search the content types of the messages parts, discarding all parts with a matching MIME type. If the message's outer content type matches the filter, the entire message will be discarded. +:: >>> from mailman.interfaces.mime import FilterAction @@ -82,6 +83,7 @@ Simple multipart filtering If one of the subparts in a multipart message matches the filter type, then just that subpart will be stripped. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -121,18 +123,18 @@ just that subpart will be stripped. Collapsing multipart/alternative messages ========================================= -When content filtering encounters a multipart/alternative part, and the +When content filtering encounters a ``multipart/alternative`` part, and the results of filtering leave only one of the subparts, then the -multipart/alternative may be collapsed. For example, in the following -message, the outer content type is a multipart/mixed. Inside this part is -just a single subpart that has a content type of multipart/alternative. This -inner multipart has two subparts, a jpeg and a gif. +``multipart/alternative`` may be collapsed. For example, in the following +message, the outer content type is a ``multipart/mixed``. Inside this part is +just a single subpart that has a content type of ``multipart/alternative``. +This inner multipart has two subparts, a jpeg and a gif. -Content filtering will remove the jpeg part, leaving the multipart/alternative -with only a single gif subpart. Because there's only one subpart left, the -MIME structure of the message will be reorganized, removing the inner -multipart/alternative so that the outer multipart/mixed has just a single gif -subpart. +Content filtering will remove the jpeg part, leaving the +``multipart/alternative`` with only a single gif subpart. Because there's +only one subpart left, the MIME structure of the message will be reorganized, +removing the inner ``multipart/alternative`` so that the outer +``multipart/mixed`` has just a single gif subpart. >>> mlist.collapse_alternatives = True >>> msg = message_from_string("""\ @@ -174,10 +176,11 @@ subpart. --BOUNDARY-- <BLANKLINE> -When the outer part is a multipart/alternative and filtering leaves this outer -part with just one subpart, the entire message is converted to the left over -part's content type. In other words, the left over inner part is promoted to -being the outer part. +When the outer part is a ``multipart/alternative`` and filtering leaves this +outer part with just one subpart, the entire message is converted to the left +over part's content type. In other words, the left over inner part is +promoted to being the outer part. +:: >>> mlist.filter_types = ['image/jpeg', 'text/html'] >>> msg = message_from_string("""\ @@ -214,16 +217,16 @@ Conversion to plain text Many mailing lists prohibit HTML email, and in fact, such email can be a phishing or spam vector. However, many mail readers will send HTML email by default because users think it looks pretty. One approach to handling this -would be to filter out text/html parts and rely on multipart/alternative -collapsing to leave just a plain text part. This works because many mail -readers that send HTML email actually send a plain text part in the second -subpart of such multipart/alternatives. +would be to filter out ``text/html`` parts and rely on +``multipart/alternative`` collapsing to leave just a plain text part. This +works because many mail readers that send HTML email actually send a plain +text part in the second subpart of such ``multipart/alternatives``. While this is a good suggestion for plain text-only mailing lists, often a -mail reader will send only a text/html part with no plain text alternative. -in this case, the site administer can enable text/html to text/plain -conversion by defining a conversion command. A list administrator still needs -to enable such conversion for their list though. +mail reader will send only a ``text/html`` part with no plain text +alternative. in this case, the site administer can enable ``text/html`` to +``text/plain`` conversion by defining a conversion command. A list +administrator still needs to enable such conversion for their list though. >>> mlist.convert_html_to_plaintext = True @@ -270,8 +273,8 @@ Discarding empty parts Similarly, if after filtering a multipart section ends up empty, then the entire multipart is discarded. For example, here's a message where an inner -multipart/mixed contains two jpeg subparts. Both jpegs are filtered out, so -the entire inner multipart/mixed is discarded. +``multipart/mixed`` contains two jpeg subparts. Both jpegs are filtered out, +so the entire inner ``multipart/mixed`` is discarded. >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -341,4 +344,4 @@ Passing MIME types ================== XXX Describe the pass_mime_types setting and how it interacts with -filter_mime_types. +``filter_mime_types``. diff --git a/src/mailman/pipeline/docs/nntp.txt b/src/mailman/pipeline/docs/nntp.txt index 5c859c0ae..874712397 100644 --- a/src/mailman/pipeline/docs/nntp.txt +++ b/src/mailman/pipeline/docs/nntp.txt @@ -9,12 +9,13 @@ NNTP is to Usenet as IP is to the web, it's more general than that. >>> mlist = create_list('_xtest@example.com') Gatewaying from the mailing list to the newsgroup happens through a separate -'nntp' queue and happen immediately when the message is posted through to the -list. Note that gatewaying from the newsgroup to the list happens via a -cronjob (currently not shown). +``nntp`` queue and happen immediately when the message is posted through to +the list. Note that gatewaying from the newsgroup to the list happens via a +cronjob (currently not shown). There are several situations which prevent a message from being gatewayed to the newsgroup. The feature could be disabled, as is the default. +:: >>> mlist.gateway_to_news = False >>> msg = message_from_string("""\ |