Stephen Turnbull has proposed merging lp:~stephen-xemacs/mailman/docs-20130720
into lp:mailman.
Requested reviews:
Mailman Coders (mailman-coders)
For more details, see:
https://code.launchpad.net/~stephen-xemacs/mailman/docs-20130720/+merge/176021
Minor doc improvements:
- major rewrite of MTA.rst
- to graphs in 8-miles-high.rst
- requires exactly Python 2.7 (don't imply 2.8 will ever happen) in
INTRODUCTION.rst
- refactor some parts of START.rst
--
https://code.launchpad.net/~stephen-xemacs/mailman/docs-20130720/+merge/176021
Your team Mailman Coders is requested to review the proposed merge of
lp:~stephen-xemacs/mailman/docs-20130720 into lp:mailman.
=== modified file 'src/mailman/docs/8-miles-high.rst'
--- src/mailman/docs/8-miles-high.rst 2013-03-19 01:31:52 +0000
+++ src/mailman/docs/8-miles-high.rst 2013-07-20 18:39:23 +0000
@@ -37,10 +37,12 @@
node [shape=box, color=lightblue, style=filled];
msg [shape=ellipse, color=black, fillcolor=white];
lmtpd [label="LMTP\nSERVER"];
+ rts [label="Return\nto Sender"];
msg -> MTA [label="SMTP"];
MTA -> lmtpd [label="LMTP"];
lmtpd -> MTA [label="reject"];
lmtpd -> IN -> PIPELINE [label=".pck"];
+ IN -> rts;
lmtpd -> BOUNCES [label=".pck"];
lmtpd -> COMMAND [label=".pck"];
}
@@ -49,7 +51,9 @@
whether the post (or administrative request) will be processed. If not
allowed, the message pickle is discarded, rejected (returned to sender), or
held (saved for moderator approval -- not shown). Otherwise the message is
-added to the `pipeline` (i.e. posting) queue.
+added to the `pipeline` (i.e. posting) queue. (Note that rejecting at this
+stage is *not* equivalent to rejecting during LMTP processing. This issue is
+currently unresolved.)
Each of the `command`, `bounce`, and `pipeline` queues is processed by a
*pipeline of handlers* as in Mailman 2's pipeline. (Some functions such as
@@ -60,7 +64,8 @@
posted messages for distribution to the list membership end up in the `out`
queue for injection into the MTA.
-The `virgin` queue is a special queue for messages created by Mailman.
+The `virgin` queue (not depicted above) is a special queue for messages created
+by Mailman.
.. graphviz::
@@ -97,12 +102,13 @@
subgraph rules {
rankdir=TB;
node [shape=record];
- approved [label="<in> approved | { <no> | <yes> }"];
- emergency [label="<in> emergency | { <no> | <yes> }"];
- loop [label="<in> loop | { <no> | <yes> }"];
- modmember [label="<in> member\nmoderated | { <no> | <yes> }"];
- administrivia [group="0", label="<in> administrivia | <always> "];
- maxsize [label="<in> max\ size | {<in> no | <yes>}"];
+ approved [label="<in> approved | { <no> no | <yes> }"];
+ emergency [label="<in> emergency | { <no> no | <yes> }"];
+ loop [label="<in> loop | { <no> no | <yes> }"];
+ modmember [label="<in> member\nmoderated | { <no> no | <yes> }"];
+ administrivia [group="0",
+ label="<in> administrivia | { <no> no | <yes> }"];
+ maxsize [label="<in> max\ size | {<no> no | <yes>}"];
any [label="<in> any | {<no> | <yes>}"];
truth [label="<in> truth | <always>"];
@@ -114,6 +120,7 @@
DISCARD [shape=invhouse, color=black, style=solid];
MODERATION [color=wheat];
HOLD [color=wheat];
+ action [color=wheat];
}
{ PIPELINE [shape=box, style=filled, color=cyan]; }
@@ -130,7 +137,8 @@
modmember:no -> administrivia:in;
modmember:yes -> MODERATION;
- administrivia:always -> maxsize:in;
+ administrivia:no -> maxsize:in;
+ administrivia:yes -> action;
maxsize:no -> any:in;
maxsize:yes -> MODERATION;
@@ -145,7 +153,7 @@
Configuration
=============
-Uses `lazr.config`_, essentially an "ini"-style configuration format.
+Mailman 3 uses `lazr.config`_, essentially an "ini"-style configuration format.
Each Runner's configuration object knows whether it should be started
when the Mailman daemon starts, and what queue the Runner manages.
=== modified file 'src/mailman/docs/INTRODUCTION.rst'
--- src/mailman/docs/INTRODUCTION.rst 2013-01-01 14:05:42 +0000
+++ src/mailman/docs/INTRODUCTION.rst 2013-07-20 18:39:23 +0000
@@ -82,7 +82,7 @@
Requirements
============
-Mailman 3.0 requires `Python 2.7`_ or newer.
+Mailman 3.0 requires `Python 2.7`_.
.. _`GNU Mailman`: http://www.list.org
=== modified file 'src/mailman/docs/MTA.rst'
--- src/mailman/docs/MTA.rst 2012-12-30 23:24:26 +0000
+++ src/mailman/docs/MTA.rst 2013-07-20 18:39:23 +0000
@@ -2,34 +2,75 @@
Hooking up your mail server
===========================
-Mailman needs to be hooked up to your mail server (a.k.a. *mail transport
-agent* or *MTA*) both to accept incoming mail and to deliver outgoing mail.
-Mailman itself never delivers messages to the end user; it lets its immediate
-upstream mail server do that.
-
-The preferred way to allow Mailman to accept incoming messages from your mail
-server is to use the `Local Mail Transfer Protocol`_ (LMTP_) interface. Most
-open source mail server support LMTP for local delivery, and this is much more
-efficient than spawning a process just to do the delivery.
-
-Your mail server should also accept `Simple Mail Transfer Protocol`_ (SMTP_)
-connections from Mailman, for all outgoing messages.
-
-The specific instructions for hooking your mail server up to Mailman differs
-depending on which mail server you're using. The following are instructions
-for the popular open source mail servers.
-
-Note that Mailman provides lots of configuration variables that you can use to
-tweak performance for your operating environment. See the
+Mailman needs to communicate with your *MTA* (*mail transport agent*
+or *mail server*, the software which handles sending mail across the
+Internet), both to accept incoming mail and to deliver outgoing mail.
+Mailman itself never delivers messages to the end user. It sends them
+to its immediate upstream MTA, which delivers them. In the same way,
+Mailman never receives mail directly. Mail from outside always comes
+via the MTA.
+
+Mailman accepts incoming messages from the MTA using the `Local Mail
+Transfer Protocol`_ (LMTP_) interface. Mailman can use other incoming
+transports, but LMTP is much more efficient than spawning a process
+just to do the delivery. Most open source MTAs support LMTP for local
+delivery. If yours doesn't, and you need to use a different
+interface, please ask on the `mailing list or on IRC`_.
+
+Mailman passes all outgoing messages to the MTA using the `Simple Mail
+Transfer Protocol`_ (SMTP_).
+
+Cooperation between Mailman and the MTA requires some configuration of
+both. MTA configuration differs for each of the available MTAs, and
+there is a section for each one. Instructions for Postfix are given
+below. We would really appreciate contributions of configurations for
+Exim and Sendmail, and welcome information about other popular open
+source mail servers.
+
+Configuring Mailman to communicate with the MTA is straightforward,
+and basically the same for all MTAs. In your ``mailman.cfg`` file,
+add (or edit) a section like the following::
+
+ [mta]
+ incoming: mailman.mta.postfix.LMTP
+ outgoing: mailman.mta.deliver.deliver
+ lmtp_host: 127.0.0.1
+ lmtp_port: 8024
+ smtp_host: localhost
+ smtp_port: 25
+
+This configuration is for a system where Mailman and the MTA are on
+the same host.
+
+The ``incoming`` and ``outgoing`` parameters identify the Python
+objects used to communicate with the MTA. The ``deliver`` module used
+in ``outgoing`` is pretty standard across all MTAs. The ``postfix``
+module in ``incoming`` is specific to Postfix. See the section for
+your MTA below for details on these parameters.
+
+``lmtp_host`` and ``lmtp_port`` are parameters which are used by
+Mailman, but also will be passed to the MTA to identify the Mailman
+host. The "same host" case is special; some MTAs (including Postfix)
+do not recognize "localhost", and need the numerical IP address. If
+they are on different hosts, ``lmtp_host`` should be set to the domain
+name or IP address of the Mailman host. ``lmtp_port`` is fairly
+arbitrary (there is no standard port for LMTP). Use any port
+convenient for your site. "8024" is as good as any, unless another
+service is using it.
+
+``smtp_host`` and ``smtp_port`` are parameters used to identify the
+MTA to Mailman. If the MTA and Mailman are on separate hosts,
+``smtp_host`` should be set to the domain name or IP address of the
+MTA host. ``smtp_port`` will almost always be 25, which is the
+standard port for SMTP. (Some special site configurations set it to a
+different port. If you need this, you probably already know that,
+know why, and what to do, too!)
+
+Mailman also provides many other configuration variables that you can
+use to tweak performance for your operating environment. See the
``src/mailman/config/schema.cfg`` file for details.
-Exim
-====
-
-Contributions are welcome!
-
-
Postfix
=======
@@ -131,12 +172,19 @@
.. _`mydestination`: http://www.postfix.org/postconf.5.html#mydestination
+Exim
+====
+
+Contributions are welcome!
+
+
Sendmail
========
Contributions are welcome!
+.. _`mailing list or on IRC`: START.html#contact-us
.. _`Local Mail Transfer Protocol`:
http://en.wikipedia.org/wiki/Local_Mail_Transfer_Protocol
.. _LMTP: http://www.faqs.org/rfcs/rfc2033.html
=== modified file 'src/mailman/docs/START.rst'
--- src/mailman/docs/START.rst 2013-01-01 14:05:42 +0000
+++ src/mailman/docs/START.rst 2013-07-20 18:39:23 +0000
@@ -25,25 +25,33 @@
implementation is provided). The web interface (known as `Postorius`_) and
archiver (known as `Hyperkitty`_) are in separate development.
-Contributions are welcome. Please submit bug reports on the Mailman bug
-tracker at https://bugs.launchpad.net/mailman though you will currently need
-to have a login on Launchpad to do so. You can also send email to the
[email protected] mailing list.
+
+Contact Us
+==========
+
+Contributions of code, problem reports, and feature requests are welcome.
+Please submit bug reports on the Mailman bug tracker at
+https://bugs.launchpad.net/mailman (you need to have a login on Launchpad to
+do so). You can also send email to the [email protected] mailing
+list, or ask on IRC channel #mailman on Freenode.
Requirements
============
Python 2.7 is required. It can either be the default 'python' on your
-``$PATH`` or it can be accessible via the ``python2.7`` binary.
-If your operating system does not include Python, see http://www.python.org
-downloading and installing it from source. Python 3 is not yet supported.
+``$PATH`` or it can be accessible via the ``python2.7`` binary. If
+your operating system does not include Python, see http://www.python.org
+for information about downloading installers (where available) and
+installing it from source (when necessary or preferred). Python 3 is
+not yet supported.
In this documentation, a bare ``python`` refers to the Python executable used
to invoke ``bootstrap.py``.
-Mailman 3 is now based on the `zc.buildout`_ infrastructure, which greatly
-simplifies testing Mailman. Buildout is not required for installation.
+The Mailman 3 build is now based on the `zc.buildout`_ infrastructure, which
+greatly simplifies testing Mailman. Buildout is not required for installation
+of Mailman from a package.
During the beta program, you may need some additional dependencies, such as a
C compiler and the Python development headers and libraries. You will need an
@@ -149,8 +157,9 @@
``bin/mailman start`` to start the runner subprocess daemons, and of course
``bin/mailman stop`` to stop them.
-Postorius is being developed as a separate, Django-based project. For now,
-all configuration happens via the command line and REST API.
+Postorius, a web UI for administration and subscriber settings, is being
+developed as a separate, Django-based project. For now, the most flexible
+means of configuration is via the command line and REST API.
Mailman Web UI
@@ -167,16 +176,16 @@
of Mailman 3 beta 1, and comes in several components. In particular, it
requires a `Django`_ installation, and Bazaar checkouts of the `REST client
module`_ and `Postorius`_ itself. Building it is fairly straightforward,
-however, given Florian Fuchs' `Five Minute Guide` from his `blog post`_ on the
+based on Florian Fuchs' `Five Minute Guide` from his `blog post`_ on the
Mailman wiki. (Check the `blog post`_ for the most recent version!)
The Archiver
------------
-In Mailman 3, the archivers are decoupled from the core engine. It is useful
-to provide a simple, standard interface for third-party archiving tools and
-services. For this reason, Mailman 3 defines a formal interface to insert
+In Mailman 3, the archivers are decoupled from the core engine. Instead,
+Mailman 3 provides a simple, standard interface for third-party archiving tools
+and services. For this reason, Mailman 3 defines a formal interface to insert
messages into any of a number of configured archivers, using whatever protocol
is appropriate for that archiver. Summary, search, and retrieval of archived
posts are handled by a separate application.
_______________________________________________
Mailman-coders mailing list
[email protected]
http://mail.python.org/mailman/listinfo/mailman-coders
