10 files changed, 156 insertions, 176 deletions

diff --git a/src/mailman/docs/STYLEGUIDE.rst b/src/mailman/docs/STYLEGUIDE.rst
index 503b98db5..d5bbdc1ae 100644
--- a/src/mailman/docs/STYLEGUIDE.rst
+++ b/src/mailman/docs/STYLEGUIDE.rst
@@ -1,17 +1,17 @@
-==============================
-GNU Mailman Coding Style Guide
-==============================
+================================
+ GNU Mailman Coding Style Guide
+================================
 
 Copyright (C) 2002-2017 Barry A. Warsaw
 
 
-Python coding style guide for GNU Mailman
-=========================================
+Python coding style guide for GNU Mailman Core
+==============================================
 
 This document contains a style guide for Python programming, as used in GNU
-Mailman.  `PEP 8`_ is the basis for this style guide so its recommendations
-should be followed except for the differences outlined here.  This document
-assumes the use of Python 3.
+Mailman Core.  `PEP 8`_ is the basis for this style guide so its
+recommendations should be followed except for the differences outlined here.
+Core is a Python 3 application, so this document assumes the use of Python 3.
 
 Much of the style guide is enforced by the command ``tox -e qa``.
 
@@ -19,8 +19,8 @@ Much of the style guide is enforced by the command ``tox -e qa``.
   an example.
 
 * Public module-global names should be exported in the ``__all__`` but use the
-  ``@public`` decorator from the top-level ``mailman`` package to do this for
-  all classes and functions.
+  ``@public`` decorator from the public_ package to do this for all classes
+  and functions.
 
 * Imports are always put at the top of the file, just after any module
   comments and docstrings, and before module globals and constants.
@@ -70,18 +70,19 @@ Much of the style guide is enforced by the command ``tox -e qa``.
              """
 
 * Write docstrings for modules, functions, classes, and methods.  Docstrings
-  can be omitted for special methods (e.g. __init__() or __str__()) where the
-  meaning is obvious.
+  can be omitted for special methods (e.g. ``__init__()`` or ``__str__()``)
+  where the meaning is obvious.
 
-* PEP 257 describes good docstrings conventions.  Note that most importantly,
-  the """ that ends a multiline docstring should be on a line by itself, e.g.::
+* `PEP 257`_ describes good docstrings conventions.  Note that most
+  importantly, the ``"""`` that ends a multiline docstring should be on a line
+  by itself, e.g.::
 
     """Return a foobang
 
     Optional plotz says to frobnicate the bizbaz first.
     """
 
-* For one liner docstrings, keep the closing """ on the same line.
+* For one liner docstrings, keep the closing ``"""`` on the same line.
 
 * ``fill-column`` for docstrings should be 78.
 
@@ -106,3 +107,5 @@ Much of the style guide is enforced by the command ``tox -e qa``.
 
 .. _`PEP 8`: http://www.python.org/peps/pep-0008.html
 .. _`GNU Mailman Python template`: https://gitlab.com/mailman/mailman/blob/master/template.py
+.. _public: https://public.readthedocs.io/en/latest/
+.. _`PEP 257`: http://www.python.org/peps/pep-0257.html
diff --git a/src/mailman/docs/ARCHITECTURE.rst b/src/mailman/docs/architecture.rst
index 3208ec842..e1d5c4ec5 100644
--- a/src/mailman/docs/ARCHITECTURE.rst
+++ b/src/mailman/docs/architecture.rst
@@ -1,6 +1,6 @@
-======================
-Mailman 3 architecture
-======================
+=============================
+ Mailman 3 Core architecture
+=============================
 
 This is a brief overview of the internal architecture of the Mailman 3 core
 delivery engine.  You should start here if you want to understand how Mailman
@@ -49,9 +49,9 @@ Process model
 Messages move around inside the Mailman system by way of *queue* directories
 managed by the *switchboard*.  For example, when a message is first received
 by Mailman, it is moved to the *in* (for "incoming") queue.  During the
-processing of this message, it -- or copies of it -- may be moved to other
-queues such as the *out* queue (for outgoing email), the *archive* queue (for
-sending to the archivers), the *digest* queue (for composing digests), etc.
+processing of this message, it -or copies of it- may be moved to other queues
+such as the *out* queue (for outgoing email), the *archive* queue (for sending
+to the archivers), the *digest* queue (for composing digests), etc.
 
 A message in a queue is represented by a single file, a ``.pck`` file.  This
 file contains two objects, serialized as `Python pickles`_.  The first object
@@ -65,7 +65,7 @@ processed.
 
 Each queue directory is associated with a *runner* process which wakes up
 every so often.  When the runner wakes up, it examines all the ``.pck`` files
-in FIFO order, deserializing the message and metadata objects, processing
+in FIFO order, deserializing the message and metadata objects, and processing
 them.  If the message needs further processing in a different queue, it will
 be re-serialized back into a ``.pck`` file.  If not (e.g. because processing
 of the message is complete), then no ``.pck`` file is written.
@@ -87,10 +87,10 @@ Rules and chains
 When a message is first received for posting to a mailing list, Mailman
 processes the message to determine whether the message is appropriate for the
 mailing list.  If so, it *accepts* the message and it gets posted.  Mailman
-can also *discard* the message so that no further processing occurs.  Mailman
-can also *reject* the message, bouncing it back to the original sender,
-usually with some indication of why the message was rejected.  Mailman can
-also *hold* the message for moderator approval.
+can *discard* the message so that no further processing occurs.  Mailman can
+also *reject* the message, bouncing it back to the original sender, usually
+with some indication of why the message was rejected.  Or, Mailman can *hold*
+the message for moderator approval.
 
 *Moderation* is the phase of processing that determines which of the above
 four dispositions will occur for the newly posted message.  Moderation does
@@ -115,7 +115,7 @@ the appropriate start chain.  The message is then passed to the chain, where
 each link in the chain first checks to see if its rule matches, and if so, it
 executes the linked action.  This action is usually one of *accept*, *reject*,
 *discard*, and *hold*, but other actions are possible, such as executing a
-function or jumping to another chain.
+function, deferring action, or jumping to another chain.
 
 As you might imagine, you can write new rules, compose them into new chains,
 and configure a mailing list to use your custom chain when processing the
@@ -149,16 +149,40 @@ Of course, you can define new handlers, compose them into new pipelines, and
 change a mailing list's pipelines.
 
 
+Integration and control
+=======================
+
+Humans and external programs can interact with a running Core system in may
+different ways.  There's an extensive command line interface that provides
+useful options to a system administrator.  For external applications such as
+the Postorius web user interface, and the HyperKitty archiver, the
+`administrative REST API <rest-api>` is the most common way to get information
+into and out of the Core.
+
+**Note**: The REST API is an administrative API and as such it must not be
+exposed to the public internet.  By default, the REST server only listens on
+``localhost``.
+
+Internally, the Python API is extensive and well-documented.  Most objects in
+the system are accessed through the `Zope Component Architecture`_ (ZCA).  If
+your Mailman installation is importable, you can write scripts directly
+against the internal public Python API.
+
+
 Other bits and pieces
 =====================
 
-There are lots of other pieces to the Mailman puzzle, such as the REST API,
-the set of core functionality (logging, initialization, event handling, etc.),
-mailing list *styles*, the API for integrating external archivers and mail
-servers.  The database layer is an critical piece, and Mailman has an
-extensive set of command line commands, and email commands.
+There are lots of other pieces to the Mailman puzzle, such as the set of core
+functionality (logging, initialization, event handling, etc.), mailing list
+*styles*, the API for integrating external archivers and mail servers.  The
+database layer is an critical piece, and Mailman has an extensive set of
+command line commands, and email commands.
+
+Almost the entire system is documented in these pages, but it maybe be a bit
+of a spelunking effort to find it.  Improvements are welcome!
 
 
 .. _`Architecture of Open Source Applications`: http://www.aosabook.org/en/mailman.html
 .. _`Python pickles`: http://docs.python.org/2/library/pickle.html
 .. _`more efficient internal representation`: https://docs.python.org/3/library/email.html
+.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
diff --git a/src/mailman/docs/CONTRIBUTE.rst b/src/mailman/docs/contribute.rst
index 15c542e3e..136a4460d 100644
--- a/src/mailman/docs/CONTRIBUTE.rst
+++ b/src/mailman/docs/contribute.rst
@@ -1,6 +1,6 @@
-=========================
-Contributing to Mailman 3
-=========================
+===========================
+ Contributing to Mailman 3
+===========================
 
 Copyright (C) 2008-2017 by the Free Software Foundation, Inc.
 
@@ -15,6 +15,8 @@ to sign a `copyright assignment`_ to the Free Software Foundation, the owner
 of the GNU Mailman copyright.  If you'd like to jump start your copyright
 assignment, please contact the GNU Mailman `steering committee`_.
 
+Please read the :doc:`STYLEGUIDE` for required coding style guidelines.
+
 
 Contact Us
 ==========
@@ -90,7 +92,7 @@ Testing with PostgreSQL and MySQL
 
 By default, the test suite runs with the built-in SQLite database engine.  If
 you want to run the full test suite against the PostgreSQL or MySQL databases,
-set the database up as described in :doc:`DATABASE`.
+set the database up as described in :doc:`database`.
 
 For PostgreSQL, then create a `postgres.cfg` file any where you want.  This
 `postgres.cfg` file will contain the ``[database]`` section for PostgreSQL,
diff --git a/src/mailman/docs/DATABASE.rst b/src/mailman/docs/database.rst
index c85731fb3..fc606a64d 100644
--- a/src/mailman/docs/DATABASE.rst
+++ b/src/mailman/docs/database.rst
@@ -1,10 +1,10 @@
-========================
-Setting up your database
-========================
+==========================
+ Setting up your database
+==========================
 
 Mailman uses the SQLAlchemy_ ORM to provide persistence of data in a
 relational database.  By default, Mailman uses Python's built-in SQLite3_
-database, however, SQLAlchemy is compatible with PostgreSQL_ and MySQL, among
+database, however, SQLAlchemy is compatible with PostgreSQL_ and MySQL_, among
 possibly others.
 
 Currently, Mailman is known to work with the SQLite3, PostgreSQL, and MySQL
@@ -26,8 +26,8 @@ As mentioned, if you want to use SQLite3 in the default configuration, you
 generally don't need to change anything.  However, if you want to change where
 the SQLite3 database is stored, you can change the ``url`` variable in the
 ``[database]`` section.  By default, the database is stored in the *data
-directory* in the ``mailman.db`` file.  Here's how you'd force Mailman to
-store its database in ``/var/lib/mailman/sqlite.db`` file::
+directory* in the ``mailman.db`` file.  Here's how to tell Mailman to store
+its database in ``/var/lib/mailman/sqlite.db`` file::
 
     [database]
     url: sqlite:////var/lib/mailman/sqlite.db
@@ -41,7 +41,7 @@ help.  Let's say you create the `mailman` database in PostgreSQL via::
 
     $ sudo -u postgres createdb -O $USER mailman
 
-You would also need the python driver `psycopg2` for Postgresql.::
+You would also need the Python driver `psycopg2` for PostgreSQL::
 
     $ pip install psycopg2
 
@@ -52,21 +52,19 @@ You would then need to set both the `class` and `url` variables in
     class: mailman.database.postgresql.PostgreSQLDatabase
     url: postgres://myuser:mypassword@mypghost/mailman
 
-That should be it.
-
 If you have any problems, you may need to delete the database and re-create
 it::
 
     $ sudo -u postgres dropdb mailman
     $ sudo -u postgres createdb -O myuser mailman
 
-My thanks to Stephen A. Goss for his contribution of PostgreSQL support.
+Many thanks to Stephen A. Goss for his contribution of PostgreSQL support.
 
 
 MySQL
 =====
 
-First, you need to configure MySQL itself.  Lets say you create the `mailman`
+First you need to configure MySQL itself.  Lets say you create the `mailman`
 database in MySQL via::
 
     mysql> CREATE DATABASE mailman;
@@ -109,8 +107,8 @@ Mailman into that, and then run the ``alembic`` command.  For example::
       "<migration_name>"
     $ deactivate
 
-This would create a new migration which would automatically be migrated to the
-database on the next run of Mailman.
+This would create a new migration which would be applied to the database
+automatically on the next run of Mailman.
 
 People upgrading Mailman from previous versions need not do anything manually,
 as soon as a new migration is added in the sources, it will be automatically
diff --git a/src/mailman/docs/ArchiveUIin5.rst b/src/mailman/docs/hyperkitty.rst
index d4b24c92c..d56031fa9 100644
--- a/src/mailman/docs/ArchiveUIin5.rst
+++ b/src/mailman/docs/hyperkitty.rst
@@ -1,6 +1,6 @@
-=====================================
-Set up the archive ui in five minutes
-=====================================
+===================================
+ Set up HyperKitty in five minutes
+===================================
 
 .. note::
    This document is way out of date.  If you have access to the Web,
@@ -9,7 +9,7 @@ Set up the archive ui in five minutes
    `FedoraHosted`_.  If you must work offline, this document may be of some
    use, but be careful.
 
-The `hyperkitty`_ application aims at providing an interface to visualize and
+The `HyperKitty`_ application aims at providing an interface to visualize and
 explore Mailman archives.
 
 This is a `Django`_ project.
@@ -18,18 +18,18 @@ Requirements
 ============
 
 - A mail archive in `maildir format`_ (no, you don't need a running Mailman
-  3!)  Eventually hyperkitty will support `mbox format`_ for backward
+  3!)  Eventually HyperKitty will support `mbox format`_ for backward
   compatibility with *Pipermail*, and *zipped maildirs* seem like a good idea
   to save space.  **Beware:** Although you'd think that we would be able to
   manipulate the venerable *mbox* format safely and efficiently, that doesn't
   seem to be the case.  *Maildir* archives are **strongly** preferred, because
-  they are more robust to program bugs (whether in Mailman, hyperkitty, or in
+  they are more robust to program bugs (whether in Mailman, HyperKitty, or in
   the originating MUA!)
 - Django is the web framework that supports the UI.
 - `bunch`_ DOES WHAT?
 - The `notmuch mail indexer`_ is used to generate indexes (and requires
   `Xapian`_).
-- hyperkitty itself, which is a UI, and not responsible for maintaining the
+- HyperKitty itself, which is a UI, and not responsible for maintaining the
   message archive itself.  (Since the archive is in `maildir format`_, any
   modern MTA or MDA can build one for you.)
 
@@ -73,14 +73,14 @@ omit the preceding steps.  Continue with these steps.
 
     % ln -s /usr/lib/python2.7/site-packages/notmuch-0.11-py2.7.egg-info .
 
-- Install the hyperkitty sources::
+- Install the HyperKitty sources::
 
     % git clone https://github.com/hyperkitty/kittystore.git
     % git clone https://github.com/hyperkitty/hyperkitty.git
     % git clone https://github.com/hyperkitty/hyperkitty_standalone.git
 
 
-Running hyperkitty
+Running HyperKitty
 ------------------
 
 - Start it::
@@ -98,7 +98,7 @@ Running hyperkitty
 
 .. _`Development Setup Guide`: https://fedorahosted.org/hyperkitty/wiki/DevelopmentSetupGuide
 .. _`FedoraHosted`: https://fedorahosted.org/
-.. _`hyperkitty`: https://fedorahosted.org/hyperkitty/
+.. _`HyperKitty`: https://fedorahosted.org/hyperkitty/
 .. _`Django`: http://djangoproject.org/
 .. _`notmuch mail indexer`: http://notmuchmail.org
 .. _`bunch`: http://pypi.python.org/pypi/bunch
diff --git a/src/mailman/docs/INSTALL.rst b/src/mailman/docs/install.rst
index 8a4722190..227fc087c 100644
--- a/src/mailman/docs/INSTALL.rst
+++ b/src/mailman/docs/install.rst
@@ -1,6 +1,6 @@
-====================
-Installing Mailman 3
-====================
+======================
+ Installing Mailman 3
+======================
 
 Copyright (C) 2008-2017 by the Free Software Foundation, Inc.
 
@@ -28,6 +28,9 @@ core documentation (such as this file) is found in the ``src/mailman/docs``
 directory, but much of the documentation is in module-specific places.  Online
 versions of the `Mailman 3 Core documentation`_ is available online.
 
+Also helpful might be Mark Sapiro's documentation on `building out the
+mailman3.org`_ server.
+
 
 Get the sources
 ===============
@@ -47,43 +50,25 @@ Running Mailman 3
 
 You will need to set up a configuration file to override the defaults and set
 things up for your environment.  Mailman is configured using an "ini"-style
-configuration system.
-
-``src/mailman/config/schema.cfg`` defines the ini-file schema and contains
-documentation for every section and configuration variable.  Sections that end
-in ``.template`` or ``.master`` are templates that must be overridden in
-actual configuration files.  There is a default configuration file that
-defines these basic overrides in ``src/mailman/config/mailman.cfg``.  Your own
-configuration file will override those.
+configuration system.  Usually this means creating a ``mailman.cfg`` file and
+putting it in a standard search location.  See the :ref:`configuration
+<configuration>` documentation for details.
 
 By default, all runtime files are put under a ``var`` directory in the current
 working directory.
 
-Mailman searches for its configuration file using the following search path.
-The first existing file found wins.
-
-* ``-C config`` command line option
-* ``$MAILMAN_CONFIG_FILE`` environment variable
-* ``./mailman.cfg``
-* ``~/.mailman.cfg``
-* ``/etc/mailman.cfg``
-* ``argv[0]/../../etc/mailman.cfg``
-
-Run the ``mailman info`` command to see which configuration file Mailman will
-use, and where it will put its database file.  The first time you run this,
+Run the ``mailman info`` command to see which configuration file Mailman is
+using, and where it will put its database file.  The first time you run this,
 Mailman will also create any necessary run-time directories and log files.
 
 Try ``mailman --help`` for more details.  You can use the commands
 ``mailman start`` to start the runner subprocess daemons, and of course
 ``mailman stop`` to stop them.
 
-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.
-
-Note that you can also "run" Mailman from one of the virtual environments
+Note that you can also run Mailman from one of the virtual environments
 created by tox, e.g.::
 
+    $ tox -e py35-nocov --notest -r
     $ .tox/py35-nocov/bin/mailman info
 
 
@@ -94,7 +79,7 @@ This documentation has examples which use the Mailman shell to interact with
 Mailman.  To start the shell type ``mailman shell`` in your terminal.
 
 There are some testings functions which need to be imported first before you
-use them. They can be imported from the modules available in
+use them.  They can be imported from the modules available in
 ``mailman.testing``.  For example, to use ``dump_list`` you first need to
 import it from the ``mailman.testing.documentation`` module.
 
@@ -114,7 +99,7 @@ do::
     >>> list_manager = getUtility(IListManager)
 
 
-.. _`Postorius`: https://gitlab.com/mailman/postorius
 .. _`Python Cheeseshop`: http://pypi.python.org/pypi
 .. _`Mailman 3 Core documentation`: https://mailman.readthedocs.io
 .. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
+.. _`building out the mailman3.org`: https://wiki.list.org/DOC/Mailman%203%20installation%20experience
diff --git a/src/mailman/docs/INTRODUCTION.rst b/src/mailman/docs/introduction.rst
index e62dae183..9814796cd 100644
--- a/src/mailman/docs/INTRODUCTION.rst
+++ b/src/mailman/docs/introduction.rst
@@ -21,13 +21,12 @@ GNU Mailman 3 consists of a `suite of programs`_ that work together:
 * HyperKitty; the web-based archiver
 * Mailman client; the official Python bindings for talking to the Core's REST
   administrative API.
-* Mailman bundler; a convenient way to deploy Mailman 3.
 
-Only the Core is required.  You could easily write your own web user interface
-or archiver that speaks to the Core over its REST API.  The REST API is a pure
-HTTP-based API so you don't *have* to use Python, or even our official
-bindings.  And you can deploy whatever components you want using whatever
-mechanisms you want.
+Only the Core is required.  You can write or integrate your own web user
+interface or archiver that speaks to the Core over its REST API.  The REST API
+is a pure HTTP-based API so you don't *have* to use Python, or even our
+official bindings.  And you can deploy whatever components you want using
+whatever mechanisms you want.
 
 But we really like Postorius and HyperKitty and hope you will too!
 
@@ -67,39 +66,25 @@ Mailman was originally developed by John Viega in the mid-1990s.  Subsequent
 development (through version 1.0b3) was by Ken Manheimer.  Further work
 towards the 1.0 final release was a group effort, with the core contributors
 being: Barry Warsaw, Ken Manheimer, Scott Cotton, Harald Meland, and John
-Viega.  Version 1.0 and beyond have been primarily maintained by Barry Warsaw
-with contributions from many; see the `ACKNOWLEDGMENTS`_ file for details.
-Jeremy Hylton helped considerably with the Pipermail code in Mailman 2.0.
-Mailman 2.1 is primarily maintained by Mark Sapiro, with previous help by
-Tokio Kikuchi.  Barry Warsaw is the lead developer on Mailman 3.  Aurélien
+Viega.  Since version 1.0 the project has been led by Barry Warsaw with
+contributions from many; see the `ACKNOWLEDGMENTS`_ file for details.  Jeremy
+Hylton helped considerably with the Pipermail code in Mailman 2.0.  Mailman
+2.1 is primarily maintained by Mark Sapiro, with previous help by Tokio
+Kikuchi (RIP).  Barry Warsaw is the lead developer on Mailman 3.  Aurélien
 Bompard and Florian Fuchs lead development of Postorius and HyperKitty.
-Abhilash Raj is a valued contributor to all bits and maintains the CI
-infrastructure.
+Abhilash Raj is a core developer contributing to all the bits and maintains
+the CI infrastructure.
 
 
 Project details
 ===============
 
-The Mailman home page is:
-
-* http://www.list.org
-
-The community driven wiki (including the FAQ_) is at:
-
-* http://wiki.list.org
-
-Other help resources, such as on-line documentation, links to the mailing
-lists and archives, etc., are available at:
-
-* http://www.list.org/help.html
-
-Mailman 3 is maintained on GitLab:
-
-* https://gitlab.com/groups/mailman
-
-You can report issues in the Core at:
-
-* https://gitlab.com/mailman/mailman/issues
+* Project home page: http://www.list.org
+* Documentation: https: https://mailman.readthedocs.io
+* The community driven wiki (including the FAQ_): https://wiki.list.org
+* Additional help resources: http://www.list.org/help.html
+* Report Core bugs at: https://gitlab.com/mailman/mailman/issues
+* Mailman 3 suite on GitLab: https://gitlab.com/groups/mailman
 
 (GNU Mailman 2.1 is still maintained on Launchpad_.)
 
diff --git a/src/mailman/docs/MTA.rst b/src/mailman/docs/mta.rst
index ac38c3026..2a7f3d6d9 100644
--- a/src/mailman/docs/MTA.rst
+++ b/src/mailman/docs/mta.rst
@@ -1,6 +1,6 @@
-===========================
-Hooking up your mail server
-===========================
+=============================
+ Hooking up your mail server
+=============================
 
 Mailman needs to communicate with your *MTA* (*mail transport agent*
 or *mail server*, the software which handles sending mail across the
@@ -10,12 +10,11 @@ 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 accepts incoming messages from the MTA using the `Local Mail Transfer
+Protocol`_ (LMTP_) interface.  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_).
@@ -50,6 +49,10 @@ and other attributes of the communication channel.  This is why some
 constraints on the format of attributes arise (e.g., ``lmtp_host``), even
 though Mailman itself has no problem with them.
 
+It is possible (although not documented here) to completely replace or
+override the default mechanisms to handle both incoming and outgoing mail.
+Mailman is highly customizable here!
+
 The ``incoming`` and ``outgoing`` parameters identify the Python objects used
 to communicate with the MTA.  The ``python:`` scheme indicates that the paths
 should be a dotted Python module specification.  The ``deliver`` module used
@@ -57,23 +60,21 @@ in ``outgoing`` should be satisfactory for most MTAs.  The ``postfix`` module
 in ``incoming`` is specific to the Postfix MTA.  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.
+``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!)
+``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
@@ -317,9 +318,9 @@ Mostly defaults in mailman.cfg::
     # changed if there is a conflict with other software using that port.
     lmtp_port: 8024
 
-This will listen on localhost:8024 with LMTP and deliver outgoing
-messages to localhost:25.  See ``mailman/config/schema.cfg`` for more
-information on these settings.
+This will listen on ``localhost:8024`` with LMTP and deliver outgoing messages
+to ``localhost:25``.  See ``mailman/config/schema.cfg`` for more information
+on these settings.
 
 qmail configuration
 -------------------
diff --git a/src/mailman/docs/WebUIin5.rst b/src/mailman/docs/postorius.rst
index 70716e6a7..f1cc2b96e 100644
--- a/src/mailman/docs/WebUIin5.rst
+++ b/src/mailman/docs/postorius.rst
@@ -1,27 +1,27 @@
-================================
-Set up Postorius in five minutes
-================================
+==================================
+ Set up Postorius in five minutes
+==================================
 
 This is a quick guide for setting up a development environment to work on
 Mailman 3's web UI, called Postorius.  If all goes as planned, you should be
 done within 5 minutes.  This has been tested on Ubuntu 11.04.
 
 In order to download the components necessary you need to have the `Git`_
-version control system installed on your system.  Mailman requires Python 3.4,
-while mailman.client needs at least Python version 2.6.
+version control system installed on your system.  Mailman requires Python 3.4
+or newer, while mailman.client needs at least Python version 2.6.
 
 It's probably a good idea to set up a virtual Python environment using
 `virtualenv`_.  `Here is a brief HOWTO`_.  You would need two separate virtual
 environment one using Python version 2.6 or 2.7 (for Postorius and
-mailman.client) and other using Python version 3.4 (for Mailman core).
+mailman.client) and other using Python 3 (for Mailman core).
 
 .. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
 .. _`Here is a brief HOWTO`: ./ArchiveUIin5.html#get-it-running-under-virtualenv
 .. _`Git`: http://git-scm.com
 
 
-GNU Mailman 3
-=============
+Mailman Core
+============
 
 First download the latest revision of Mailman 3 from Gitlab.
 ::
@@ -81,21 +81,3 @@ a project already developed which you can set up like this::
   $(py2) python manage.py runserver
 
 The last command will start the dev server on http://localhost:8000.
-
-
-A note for MacOS X users (and possibly others running python 2.7)
-=================================================================
-
-*Note: These paragraphs are struck-through on the Mailman wiki.*
-
-On an OS X 10.7 (Lion) system, some of these steps needed to be modified to
-use python2.6 instead of python. (In particular, bzr is known to behave badly
-when used python2.7 on OS X 10.7 at the moment -- hopefully this will be fixed
-and no longer an issue soon.)
-
-You will need to install the latest version of XCode on MacOS 10.7, which is
-available for free from the App Store.  If you had a previous version of XCode
-installed when you upgraded to 10.7, it will no longer work and will not have
-automatically been upgraded, so be prepared to install again.  Once you have
-it installed from the App Store, you will still need to go run the installer
-from ``/Applications`` to complete the installation.
diff --git a/src/mailman/docs/RELEASENOTES.rst b/src/mailman/docs/release-notes.rst
index bccb03bf8..bccb03bf8 100644
--- a/src/mailman/docs/RELEASENOTES.rst
+++ b/src/mailman/docs/release-notes.rst