diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/pipeline/docs/reply-to.txt | 41 | ||||
| -rw-r--r-- | src/mailman/pipeline/docs/replybot.txt | 37 | ||||
| -rw-r--r-- | src/mailman/pipeline/docs/scrubber.txt | 16 |
3 files changed, 55 insertions, 39 deletions
diff --git a/src/mailman/pipeline/docs/reply-to.txt b/src/mailman/pipeline/docs/reply-to.txt index 841320f7f..e08fea81d 100644 --- a/src/mailman/pipeline/docs/reply-to.txt +++ b/src/mailman/pipeline/docs/reply-to.txt @@ -2,7 +2,7 @@ Reply-to 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 @@ -10,20 +10,21 @@ is getting sent through the system. We'll take things one-by-one. >>> mlist = create_list('_xtest@example.com') -Reply-to munging refers to the behavior where a mailing list can be configured -to change or augment an existing Reply-To header in a message posted to the -list. Reply-to munging is fairly controversial, with arguments made either -for or against munging. +*Reply-to munging* refers to the behavior where a mailing list can be +configured to change or augment an existing ``Reply-To`` header in a message +posted to the list. Reply-to munging is fairly controversial, with arguments +made either for or against munging. The Mailman developers, and I believe the majority consensus is to do no -Reply-to munging, under several principles. Primarily, most reply-to munging -is requested by people who do not have both a Reply and Reply All button on -their mail reader. If you do not munge Reply-To, then these buttons will work -properly, but if you munge the header, it is impossible for these buttons to -work right, because both will reply to the list. This leads to unfortunate -accidents where a private message is accidentally posted to the entire list. +reply-to munging, under several principles. Primarily, most reply-to munging +is requested by people who do not have both a `Reply` and `Reply All` button +on their mail reader. If you do not munge ``Reply-To``, then these buttons +will work properly, but if you munge the header, it is impossible for these +buttons to work right, because both will reply to the list. This leads to +unfortunate accidents where a private message is accidentally posted to the +entire list. -However, Mailman gives list owners the option to do Reply-To munging anyway, +However, Mailman gives list owners the option to do reply-To munging anyway, mostly as a way to shut up the really vocal minority who seem to insist on this mis-feature. @@ -31,9 +32,10 @@ this mis-feature. Reply to list ============= -A list can be configured to add a Reply-To header pointing back to the mailing -list's posting address. If there's no Reply-To header in the original -message, the list's posting address simply gets inserted. +A list can be configured to add a ``Reply-To`` header pointing back to the +mailing list's posting address. If there's no ``Reply-To`` header in the +original message, the list's posting address simply gets inserted. +:: >>> from mailman.interfaces.mailinglist import ReplyToMunging >>> mlist.reply_goes_to_list = ReplyToMunging.point_to_list @@ -51,8 +53,8 @@ message, the list's posting address simply gets inserted. >>> print msg['reply-to'] _xtest@example.com -It's also possible to strip any existing Reply-To header first, before adding -the list's posting address. +It's also possible to strip any existing ``Reply-To`` header first, before +adding the list's posting address. >>> mlist.first_strip_reply_to = True >>> msg = message_from_string("""\ @@ -85,7 +87,7 @@ get appended to whatever the original version was. Explicit Reply-To ================= -The list can also be configured to have an explicit Reply-To header. +The list can also be configured to have an explicit ``Reply-To`` header. >>> mlist.reply_goes_to_list = ReplyToMunging.explicit_header >>> mlist.reply_to_address = 'my-list@example.com' @@ -99,7 +101,8 @@ The list can also be configured to have an explicit Reply-To header. >>> print msg['reply-to'] my-list@example.com -And as before, it's possible to either strip any existing Reply-To header... +And as before, it's possible to either strip any existing ``Reply-To`` +header... >>> mlist.first_strip_reply_to = True >>> msg = message_from_string("""\ diff --git a/src/mailman/pipeline/docs/replybot.txt b/src/mailman/pipeline/docs/replybot.txt index f02b90254..3a6d75499 100644 --- a/src/mailman/pipeline/docs/replybot.txt +++ b/src/mailman/pipeline/docs/replybot.txt @@ -2,7 +2,7 @@ Automatic response handler ========================== -Mailman has a replybot handler that sends automatic responses to messages it +Mailman has a autoreply handler that sends automatic responses to messages it receives on its posting address, owner address, or robot address. Automatic responses are subject to various conditions, such as headers in the original message or the amount of time since the last auto-response. @@ -15,10 +15,11 @@ Basic automatic responding ========================== Basic automatic responding occurs when the list is set up to respond to either -its -owner address, its -request address, or to the posting address, and a -message is sent to one of these addresses. A mailing list also has an +its ``-owner`` address, its ``-request`` address, or to the posting address, +and a message is sent to one of these addresses. A mailing list also has an automatic response grace period which specifies how much time must pass before a second response will be sent, with 0 meaning "there is no grace period". +:: >>> import datetime >>> from mailman.interfaces.autorespond import ResponseAction @@ -36,6 +37,7 @@ a second response will be sent, with 0 meaning "there is no grace period". The preceding message to the mailing list's owner will trigger an automatic response. +:: >>> from mailman.testing.helpers import get_queue_messages @@ -73,8 +75,9 @@ Short circuiting ================ Several headers in the original message determine whether an automatic -response should even be sent. For example, if the message has an "X-Ack: No" -header, no auto-response is sent. +response should even be sent. For example, if the message has an +``X-Ack: No`` header, no auto-response is sent. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -88,7 +91,8 @@ header, no auto-response is sent. [] Mailman itself can suppress automatic responses for certain types of -internally crafted messages, by setting the 'noack' metadata key. +internally crafted messages, by setting the ``noack`` metadata key. +:: >>> msg = message_from_string("""\ ... From: mailman@example.com @@ -100,8 +104,9 @@ internally crafted messages, by setting the 'noack' metadata key. >>> get_queue_messages('virgin') [] -If there is a Precedence: header with any of the values 'bulk', 'junk', or -'list', then the automatic response is also suppressed. +If there is a ``Precedence:`` header with any of the values ``bulk``, +``junk``, or ``list``, then the automatic response is also suppressed. +:: >>> msg = message_from_string("""\ ... From: asystem@example.com @@ -124,8 +129,9 @@ If there is a Precedence: header with any of the values 'bulk', 'junk', or >>> get_queue_messages('virgin') [] -Unless the X-Ack: header has a value of "yes", in which case, the Precedence -header is ignored. +Unless the ``X-Ack:`` header has a value of ``yes``, in which case, the +``Precedence`` header is ignored. +:: >>> msg['X-Ack'] = 'yes' >>> handler.process(mlist, msg, dict(to_owner=True)) @@ -160,9 +166,10 @@ header is ignored. Available auto-responses ======================== -As shown above, a message sent to the -owner address will get an auto-response -with the text set for owner responses. Two other types of email will get -auto-responses: those sent to the -request address... +As shown above, a message sent to the ``-owner`` address will get an +auto-response with the text set for owner responses. Two other types of email +will get auto-responses: those sent to the ``-request`` address... +:: >>> mlist.autorespond_requests = ResponseAction.respond_and_continue >>> mlist.autoresponse_request_text = 'robot autoresponse text' @@ -195,6 +202,7 @@ auto-responses: those sent to the -request address... robot autoresponse text ...and those sent to the posting address. +:: >>> mlist.autorespond_postings = ResponseAction.respond_and_continue >>> mlist.autoresponse_postings_text = 'postings autoresponse text' @@ -261,6 +269,7 @@ right now. 0 Fast forward 9 days and you still don't get a response. +:: >>> from mailman.utilities.datetime import factory >>> factory.fast_forward(days=9) @@ -278,6 +287,7 @@ But tomorrow, the sender will get a new auto-response. Of course, everything works the same way for messages to the request address, even if the sender is the same person... +:: >>> msg = message_from_string("""\ ... From: bperson@example.com @@ -305,6 +315,7 @@ address, even if the sender is the same person... 1 ...and for messages to the posting address. +:: >>> msg = message_from_string("""\ ... From: bperson@example.com diff --git a/src/mailman/pipeline/docs/scrubber.txt b/src/mailman/pipeline/docs/scrubber.txt index 9c019d6e4..86a8161a7 100644 --- a/src/mailman/pipeline/docs/scrubber.txt +++ b/src/mailman/pipeline/docs/scrubber.txt @@ -11,6 +11,7 @@ archive message. >>> mlist.preferred_language = 'en' Helper functions for getting the attachment data. +:: >>> import os, re >>> def read_attachment(filename, remove=True): @@ -40,15 +41,16 @@ Helper functions for getting the attachment data. Saving attachments ================== -The Scrubber handler exposes a function called save_attachment() which can be -used to strip various types of attachments and store them in the archive +The Scrubber handler exposes a function called ``save_attachment()`` which can +be used to strip various types of attachments and store them in the archive directory. This is a public interface used by components outside the normal processing pipeline. Site administrators can decide whether the scrubber should use the attachment -filename suggested in the message's Content-Disposition: header or not. If -enabled, the filename will be used when this header attribute is present (yes, -this is an unfortunate double negative). +filename suggested in the message's ``Content-Disposition:`` header or not. +If enabled, the filename will be used when this header attribute is present +(yes, this is an unfortunate double negative). +:: >>> config.push('test config', """ ... [scrubber] @@ -81,7 +83,7 @@ Saving the attachment does not alter the original message. R0lGODdhAQABAIAAAAAAAAAAACwAAAAAAQABAAACAQUAOw== The site administrator can also configure Mailman to ignore the -Content-Disposition: filename. This is the default. +``Content-Disposition:`` filename. This is the default. >>> config.pop('test config') >>> config.push('test config', """ @@ -132,7 +134,7 @@ a reference to the attachment file as available through the on-line archive. ... """) >>> msgdata = {} -The Scrubber.process() function is different than other handler process +The ``Scrubber.process()`` function is different than other handler process functions in that it returns the scrubbed message. >>> from mailman.pipeline.scrubber import process |