diff options
Diffstat (limited to 'src/mailman/pipeline/docs/rfc-2369.rst')
| -rw-r--r-- | src/mailman/pipeline/docs/rfc-2369.rst | 206 |
1 files changed, 0 insertions, 206 deletions
diff --git a/src/mailman/pipeline/docs/rfc-2369.rst b/src/mailman/pipeline/docs/rfc-2369.rst deleted file mode 100644 index 1b89f2354..000000000 --- a/src/mailman/pipeline/docs/rfc-2369.rst +++ /dev/null @@ -1,206 +0,0 @@ -========================= -RFC 2919 and 2369 headers -========================= - -`RFC 2919`_ and `RFC 2369`_ define headers for mailing list actions. These -headers generally start with the `List-` prefix. - - >>> mlist = create_list('test@example.com') - >>> mlist.preferred_language = 'en' - >>> mlist.archive = False - -.. - This is a helper function for the following section. - >>> def list_headers(msg, only=None): - ... if isinstance(only, basestring): - ... only = (only.lower(),) - ... elif only is None: - ... only = set(header.lower() for header in msg.keys() - ... if header.lower().startswith('list-')) - ... only.add('archived-at') - ... else: - ... only = set(header.lower() for header in only) - ... print '---start---' - ... for header in sorted(only): - ... for value in sorted(msg.get_all(header, ())): - ... print '%s: %s' % (header, value) - ... print '---end---' - -The `rfc-2369` handler adds the `List-` headers. `List-Id` is always added. - - >>> from mailman.pipeline.rfc_2369 import process - >>> msg = message_from_string("""\ - ... From: aperson@example.com - ... - ... """) - >>> process(mlist, msg, {}) - >>> list_headers(msg, 'list-id') - ---start--- - list-id: <test.example.com> - ---end--- - - -Fewer headers -============= - -Some people don't like these headers because their mail readers aren't good -about hiding them. A list owner can turn these headers off. - - >>> mlist.include_rfc2369_headers = False - >>> msg = message_from_string("""\ - ... From: aperson@example.com - ... - ... """) - >>> process(mlist, msg, {}) - >>> list_headers(msg) - ---start--- - ---end--- - -Messages which Mailman generates itself, such as user or owner notifications, -have a reduced set of `List-` headers. Specifically, there is no `List-Post`, -`List-Archive` or `Archived-At` header. - - >>> mlist.include_rfc2369_headers = True - >>> mlist.include_list_post_header = False - >>> msg = message_from_string("""\ - ... From: aperson@example.com - ... - ... """) - >>> process(mlist, msg, dict(reduced_list_headers=True)) - >>> list_headers(msg) - ---start--- - list-help: <mailto:test-request@example.com?subject=help> - list-id: <test.example.com> - list-subscribe: <http://lists.example.com/listinfo/test@example.com>, - <mailto:test-join@example.com> - list-unsubscribe: <http://lists.example.com/listinfo/test@example.com>, - <mailto:test-leave@example.com> - ---end--- - - -List-Post header -================ - -Discussion lists, to which any subscriber can post, also have a `List-Post` -header which contains the `mailto:` URL used to send messages to the list. - - >>> mlist.include_list_post_header = True - >>> msg = message_from_string("""\ - ... From: aperson@example.com - ... - ... """) - >>> process(mlist, msg, {}) - >>> list_headers(msg) - ---start--- - list-help: <mailto:test-request@example.com?subject=help> - list-id: <test.example.com> - list-post: <mailto:test@example.com> - list-subscribe: <http://lists.example.com/listinfo/test@example.com>, - <mailto:test-join@example.com> - list-unsubscribe: <http://lists.example.com/listinfo/test@example.com>, - <mailto:test-leave@example.com> - ---end--- - - -List-Id header -============== - -If the mailing list has a description, then it is included in the ``List-Id`` -header. - - >>> mlist.description = 'My test mailing list' - >>> msg = message_from_string("""\ - ... From: aperson@example.com - ... - ... """) - >>> process(mlist, msg, {}) - >>> list_headers(msg) - ---start--- - list-help: <mailto:test-request@example.com?subject=help> - list-id: My test mailing list <test.example.com> - list-post: <mailto:test@example.com> - list-subscribe: <http://lists.example.com/listinfo/test@example.com>, - <mailto:test-join@example.com> - list-unsubscribe: <http://lists.example.com/listinfo/test@example.com>, - <mailto:test-leave@example.com> - ---end--- - -Any existing ``List-Id`` headers are removed from the original message. - - >>> msg = message_from_string("""\ - ... From: aperson@example.com - ... List-ID: <123.456.789> - ... - ... """) - - >>> process(mlist, msg, {}) - >>> list_headers(msg, only='list-id') - ---start--- - list-id: My test mailing list <test.example.com> - ---end--- - - -Archive headers -=============== - -When the mailing list is configured to enable archiving, a `List-Archive` -header will be added. - - >>> mlist.archive = True - -`RFC 5064`_ defines the `Archived-At` header which contains the url to the -individual message in the archives. Archivers which don't support -pre-calculation of the archive url cannot add the `Archived-At` header. -However, other archivers can calculate the url, and do add this header. - - >>> config.push('prototype', """ - ... [archiver.prototype] - ... enable: yes - ... [archiver.mail_archive] - ... enable: no - ... [archiver.mhonarc] - ... enable: no - ... [archiver.pipermail] - ... enable: No - ... """) - -The *prototype* archiver can calculate this archive url given a `Message-ID`. - - >>> msg = message_from_string("""\ - ... From: aperson@example.com - ... Message-ID: <first> - ... X-Message-ID-Hash: 4CMWUN6BHVCMHMDAOSJZ2Q72G5M32MWB - ... - ... """) - >>> process(mlist, msg, {}) - >>> list_headers(msg, only=('list-archive', 'archived-at')) - ---start--- - archived-at: http://lists.example.com/4CMWUN6BHVCMHMDAOSJZ2Q72G5M32MWB - list-archive: <http://lists.example.com> - ---end--- - -If the mailing list isn't being archived, neither the `List-Archive` nor -`Archived-At` headers will be added. - - >>> config.pop('prototype') - >>> mlist.archive = False - >>> msg = message_from_string("""\ - ... From: aperson@example.com - ... - ... """) - >>> process(mlist, msg, {}) - >>> list_headers(msg) - ---start--- - list-help: <mailto:test-request@example.com?subject=help> - list-id: My test mailing list <test.example.com> - list-post: <mailto:test@example.com> - list-subscribe: <http://lists.example.com/listinfo/test@example.com>, - <mailto:test-join@example.com> - list-unsubscribe: <http://lists.example.com/listinfo/test@example.com>, - <mailto:test-leave@example.com> - ---end--- - - -.. _`RFC 2919`: http://www.faqs.org/rfcs/rfc2919.html -.. _`RFC 2369`: http://www.faqs.org/rfcs/rfc2369.html -.. _`RFC 5064`: http://www.faqs.org/rfcs/rfc5064.html |