diff options
| -rw-r--r-- | src/mailman/archiving/docs/common.txt | 27 | ||||
| -rw-r--r-- | src/mailman/mta/docs/bulk.txt | 37 | ||||
| -rw-r--r-- | src/mailman/mta/docs/connection.txt | 25 | ||||
| -rw-r--r-- | src/mailman/mta/docs/decorating.txt | 6 | ||||
| -rw-r--r-- | src/mailman/mta/docs/personalized.txt | 18 | ||||
| -rw-r--r-- | src/mailman/mta/docs/verp.txt | 14 |
6 files changed, 82 insertions, 45 deletions
diff --git a/src/mailman/archiving/docs/common.txt b/src/mailman/archiving/docs/common.txt index 18400da42..1629458b3 100644 --- a/src/mailman/archiving/docs/common.txt +++ b/src/mailman/archiving/docs/common.txt @@ -15,12 +15,12 @@ archivers. ... Here is an archived message. ... """) -Archivers support an interface which provides the RFC 2369 List-Archive -header, and one that provides a 'permalink' to the specific message object in +Archivers support an interface which provides the RFC 2369 ``List-Archive:`` +header, and one that provides a *permalink* to the specific message object in the archive. This latter is appropriate for the message footer or for the RFC -5064 Archived-At header. +5064 ``Archived-At:`` header. -Pipermail does not support a permalink, so that interface returns None. +Pipermail does not support a permalink, so that interface returns ``None``. Mailman defines a draft spec for how list servers and archivers can interoperate. @@ -49,6 +49,7 @@ Sending the message to the archiver =================================== The archiver is also able to archive the message. +:: >>> archivers['pipermail'].archive_message(mlist, msg) @@ -71,10 +72,9 @@ Note however that the prototype archiver can't archive messages. The Mail-Archive.com ==================== -The Mail-Archive <http://www.mail-archive.com> is a public archiver that can -be used to archive message for free. Mailman comes with a plugin for this -archiver; by enabling it messages to public lists will get sent there -automatically. +`The Mail Archive`_ is a public archiver that can be used to archive message +for free. Mailman comes with a plugin for this archiver; by enabling it +messages to public lists will get sent there automatically. >>> archiver = archivers['mail-archive'] >>> print archiver.list_url(mlist) @@ -83,7 +83,8 @@ automatically. http://go.mail-archive.dev/ZaXPPxRMM9_hFZL4vTRlQlBx8pc= To archive the message, the archiver actually mails the message to a special -address at the Mail-Archive. The message gets no header or footer decoration. +address at The Mail Archive. The message gets no header or footer decoration. +:: >>> archiver.archive_message(mlist, msg) @@ -123,7 +124,8 @@ at this service. >>> list(smtpd.messages) [] -Additionally, this archiver can handle malformed Message-IDs. +Additionally, this archiver can handle malformed ``Message-IDs``. +:: >>> mlist.archive_private = False >>> del msg['message-id'] @@ -150,7 +152,7 @@ Additionally, this archiver can handle malformed Message-IDs. MHonArc ======= -The MHonArc archiver <http://www.mhonarc.org> is also available. +A MHonArc_ archiver is also available. >>> archiver = archivers['mhonarc'] >>> print archiver.name @@ -173,3 +175,6 @@ subprocess call. -stdout /.../logs/mhonarc -spammode -umask 022 ... + +.. _`The Mail Archive`: http://www.mail-archive.com +.. _MHonArc: http://www.mhonarc.org diff --git a/src/mailman/mta/docs/bulk.txt b/src/mailman/mta/docs/bulk.txt index a15a30279..8bacd4957 100644 --- a/src/mailman/mta/docs/bulk.txt +++ b/src/mailman/mta/docs/bulk.txt @@ -31,9 +31,10 @@ Delivery strategies must implement the proper interface. Chunking recipients =================== -The set of final recipients is contained in the 'recipients' key in the -message metadata. When `max_recipients` is specified as zero, then the bulk +The set of final recipients is contained in the ``recipients`` key in the +message metadata. When ``max_recipients`` is specified as zero, then the bulk deliverer puts all recipients into one big chunk. +:: >>> from string import ascii_letters >>> recipients = set(letter + 'person@example.com' @@ -56,6 +57,7 @@ more than 4 recipients, though they can have fewer (but still not zero). True The chunking algorithm sorts recipients by top level domain by length. +:: >>> recipients = set([ ... 'anne@example.com', @@ -83,8 +85,9 @@ The chunking algorithm sorts recipients by top level domain by length. 6 We can't make any guarantees about sorting within each chunk, but we can tell -a few things. For example, the first two chunks will be composed of .net (4) -and .org (3) domains (for a total of 7). +a few things. For example, the first two chunks will be composed of ``.net`` +(4) and ``.org`` (3) domains (for a total of 7). +:: >>> len(chunks[0]) 4 @@ -101,7 +104,8 @@ and .org (3) domains (for a total of 7). neil@example.net ocho@example.org -We also know that the next two chunks will contain .com (5) addresses. +We also know that the next two chunks will contain ``.com`` (5) addresses. +:: >>> len(chunks[2]) 4 @@ -116,7 +120,7 @@ We also know that the next two chunks will contain .com (5) addresses. john@example.com kate@example.com -The next chunk will contain the .us (2) and .ca (1) domains. +The next chunk will contain the ``.us`` (2) and ``.ca`` (1) domains. >>> len(chunks[4]) 3 @@ -126,7 +130,8 @@ The next chunk will contain the .us (2) and .ca (1) domains. liam@example.ca mary@example.us -The final chunk will contain the outliers, .xx (1) and .zz (2). +The final chunk will contain the outliers, ``.xx`` (1) and ``.zz`` (2). +:: >>> len(chunks[5]) 2 @@ -141,6 +146,7 @@ Bulk delivery The set of recipients for bulk delivery comes from the message metadata. If there are no calculated recipients, nothing gets sent. +:: >>> mlist = create_list('test@example.com') >>> msg = message_from_string("""\ @@ -165,7 +171,8 @@ there are no calculated recipients, nothing gets sent. With bulk delivery and no maximum number of recipients, there will be just one message sent, with all the recipients packed into the envelope recipients -(i.e. RCTP TO). +(i.e. ``RCTP TO``). +:: >>> recipients = set('person_{0:02d}'.format(i) for i in range(100)) >>> msgdata = dict(recipients=recipients) @@ -187,13 +194,14 @@ message sent, with all the recipients packed into the envelope recipients <BLANKLINE> This is a test. -The X-RcptTo header contains the set of recipients, in random order. +The ``X-RcptTo:`` header contains the set of recipients, in random order. >>> len(messages[0]['x-rcptto'].split(',')) 100 When the maximum number of recipients is set to 20, 5 messages will be sent, -each with 20 addresses in the RCPT TO header. +each with 20 addresses in the ``RCPT TO``. +:: >>> bulk = BulkDelivery(20) >>> bulk.deliver(mlist, msg, msgdata) @@ -215,11 +223,12 @@ each with 20 addresses in the RCPT TO header. Delivery headers ================ -The sending agent shows up in the RFC 5321 MAIL FROM header, which shows up in -the X-MailFrom header in the sample message. +The sending agent shows up in the RFC 5321 ``MAIL FROM``, which shows up in +the ``X-MailFrom:`` header in the sample message. The bulk delivery module calculates the sending agent address first from the message metadata... +:: >>> bulk = BulkDelivery() >>> recipients = set(['aperson@example.com']) @@ -241,6 +250,7 @@ message metadata... This is a test. ...followed by the mailing list's bounces robot address... +:: >>> del msgdata['sender'] >>> bulk.deliver(mlist, msg, msgdata) @@ -260,6 +270,7 @@ message metadata... ...and finally the site owner, if there is no mailing list target for this message. +:: >>> config.push('site-owner', """\ ... [mailman] @@ -295,6 +306,7 @@ certain situations. For example, there could be a problem delivering to any of the specified recipients. +:: # Tell the mail server to fail on the next 3 RCPT TO commands, one for # each recipient in the following message. @@ -330,6 +342,7 @@ recipients. 0 Or there could be some other problem causing an SMTP response failure. +:: # Tell the mail server to register a temporary failure on the next MAIL # FROM command. diff --git a/src/mailman/mta/docs/connection.txt b/src/mailman/mta/docs/connection.txt index a15dc4c6b..7da16a771 100644 --- a/src/mailman/mta/docs/connection.txt +++ b/src/mailman/mta/docs/connection.txt @@ -3,14 +3,14 @@ MTA connections =============== Outgoing connections to the outgoing mail transport agent (MTA) are mitigated -through a Connection class, which can transparently manage multiple sessions -in a single connection. +through a ``Connection`` class, which can transparently manage multiple +sessions in a single connection. >>> from mailman.mta.connection import Connection -The number of sessions per connections is specified when the Connection object -is created, as is the host and port number of the SMTP server. Zero means -there's an unlimited number of sessions per connection. +The number of sessions per connections is specified when the ``Connection`` +object is created, as is the host and port number of the SMTP server. Zero +means there's an unlimited number of sessions per connection. >>> connection = Connection( ... config.mta.smtp_host, int(config.mta.smtp_port), 0) @@ -21,6 +21,7 @@ At the start, there have been no connections to the server. 0 By sending a message to the server, a connection is opened. +:: >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ ... From: anne@example.com @@ -34,6 +35,7 @@ By sending a message to the server, a connection is opened. 1 We can reset the connection count back to zero. +:: >>> from smtplib import SMTP >>> def reset(): @@ -56,6 +58,7 @@ the third message is sent, the connection is torn down and a new one is created. The connection count starts at zero. +:: >>> connection = Connection( ... config.mta.smtp_host, int(config.mta.smtp_port), 2) @@ -63,8 +66,9 @@ The connection count starts at zero. >>> smtpd.get_connection_count() 0 -We send two messages through the Connection object. Only one connection is -opened. +We send two messages through the ``Connection`` object. Only one connection +is opened. +:: >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ ... From: anne@example.com @@ -88,8 +92,9 @@ opened. >>> smtpd.get_connection_count() 1 -The third message causes a third session, which exceeds the maximum. So the +The third message would cause a third session, exceeding the maximum. So the current connection is closed and a new one opened. +:: >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ ... From: anne@example.com @@ -103,6 +108,7 @@ current connection is closed and a new one opened. 2 A fourth message does not cause a new connection to be made. +:: >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ ... From: anne@example.com @@ -116,6 +122,7 @@ A fourth message does not cause a new connection to be made. 2 But a fifth one does. +:: >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ ... From: anne@example.com @@ -141,6 +148,7 @@ connection. Even after ten messages are sent, there's still been only one connection to the server. +:: >>> connection.debug = True >>> for i in range(10): @@ -163,6 +171,7 @@ Development mode By putting Mailman into development mode, you can force the recipients to a given hard-coded address. This allows you to test Mailman without worrying about accidental deliveries to unintended recipients. +:: >>> config.push('devmode', """ ... [devmode] diff --git a/src/mailman/mta/docs/decorating.txt b/src/mailman/mta/docs/decorating.txt index f89d0b102..4edac481f 100644 --- a/src/mailman/mta/docs/decorating.txt +++ b/src/mailman/mta/docs/decorating.txt @@ -21,6 +21,7 @@ Decorations Decorations are added when the mailing list had a header and/or footer defined, and the decoration handler is told to do personalized decorations. +:: >>> mlist = create_list('test@example.com') >>> mlist.msg_header = """\ @@ -59,6 +60,7 @@ defined, and the decoration handler is told to do personalized decorations. More information is included when the recipient is a member of the mailing list. +:: >>> from zope.component import getUtility >>> from mailman.interfaces.member import MemberRole @@ -81,6 +83,7 @@ list. <Member: Cris Person <cperson@example.com> ... The decorations happen when the message is delivered. +:: >>> decorating.deliver(mlist, msg, msgdata) {} @@ -154,8 +157,9 @@ The decorations happen when the message is delivered. Decorate only once ================== -Do not decorate a message twice. Decorators must insert the 'decorated' key +Do not decorate a message twice. Decorators must insert the ``decorated`` key into the message metadata. +:: >>> msgdata['nodecorate'] = True >>> decorating.deliver(mlist, msg, msgdata) diff --git a/src/mailman/mta/docs/personalized.txt b/src/mailman/mta/docs/personalized.txt index 38494b725..6c1c9eb4f 100644 --- a/src/mailman/mta/docs/personalized.txt +++ b/src/mailman/mta/docs/personalized.txt @@ -3,12 +3,10 @@ Fully personalized delivery =========================== Fully personalized mail delivery is an enhancement over VERP_ delivery where -the To field of the message is replaced with the recipient's address. A +the ``To:`` field of the message is replaced with the recipient's address. A typical email message is sent to the mailing list's posting address and copied to the list membership that way. Some people like the more personal address. -.. _VERP: verp.txt - Personalized delivery still does VERP. >>> from mailman.mta.personalized import PersonalizedDelivery @@ -25,7 +23,8 @@ Delivery strategies must implement the proper interface. No personalization ================== -By default, the To header is not personalized. +By default, the ``To:`` header is not personalized. +:: >>> mlist = create_list('test@example.com') >>> msg = message_from_string("""\ @@ -88,8 +87,9 @@ By default, the To header is not personalized. To header ========= -When the mailing list requests personalization, the To header is replaced with -the recipient's address and name. +When the mailing list requests personalization, the ``To:`` header is replaced +with the recipient's address and name. +:: >>> from mailman.interfaces.mailinglist import Personalization >>> mlist.personalize = Personalization.full @@ -136,7 +136,8 @@ the recipient's address and name. ---------- If the recipient is a user registered with Mailman, and the user has an -associated real name, then this name also shows up in the To header. +associated real name, then this name also shows up in the ``To:`` header. +:: >>> from zope.component import getUtility >>> from mailman.interfaces.usermanager import IUserManager @@ -186,3 +187,6 @@ associated real name, then this name also shows up in the To header. <BLANKLINE> This is a test. ---------- + + +.. _VERP: verp.html diff --git a/src/mailman/mta/docs/verp.txt b/src/mailman/mta/docs/verp.txt index aa7f27793..2f2f09828 100644 --- a/src/mailman/mta/docs/verp.txt +++ b/src/mailman/mta/docs/verp.txt @@ -5,9 +5,6 @@ Standard VERP delivery Variable Envelope Return Path (VERP_) delivery is an alternative to bulk_ delivery, where an individual message is crafted uniquely for each recipient. -.. _VERP: http://en.wikipedia.org/wiki/Variable_envelope_return_path -.. _bulk: bulk.html - The cost of enabling VERP is that Mailman must send to the upstream MTA, one message per recipient. Under bulk delivery, an exact copy of one message can be sent to many recipients, greatly reducing the bandwidth for delivery. @@ -20,9 +17,7 @@ e.g. pointing the user to their account URL or including a user-specific unsubscription link. In theory, VERP delivery means we can do sophisticated `mail merge`_ operations. -.. _`mail merge`: http://en.wikipedia.org/wiki/Mail_merge - -Mailman's use of the term VERP really means "message personalization". +Mailman's use of the term VERP really means *message personalization*. >>> from mailman.mta.verp import VERPDelivery >>> verp = VERPDelivery() @@ -40,6 +35,7 @@ No recipients The message metadata specifies the set of recipients to send this message to. If there are no recipients, there's nothing to do. +:: >>> mlist = create_list('test@example.com') >>> msg = message_from_string("""\ @@ -77,6 +73,7 @@ intended recipient's delivery address. ... ]) VERPing is only actually done if the metadata requests it. +:: >>> msgdata = dict(recipients=recipients, verp=True) >>> verp.deliver(mlist, msg, msgdata) @@ -130,3 +127,8 @@ The deliverer made a copy of the original message, so it wasn't changed. <BLANKLINE> This is a test. <BLANKLINE> + + +.. _VERP: http://en.wikipedia.org/wiki/Variable_envelope_return_path +.. _bulk: bulk.html +.. _`mail merge`: http://en.wikipedia.org/wiki/Mail_merge |