4 files changed, 154 insertions, 99 deletions

diff --git a/README.rst b/README.rst
index 3d412fa1b..738e647b5 100644
--- a/README.rst
+++ b/README.rst
@@ -47,6 +47,7 @@ Table of Contents
 
     src/mailman/docs/INTRODUCTION
     src/mailman/docs/RELEASENOTES
+    src/mailman/docs/INSTALL
     src/mailman/config/docs/config
     src/mailman/docs/DATABASE
     src/mailman/docs/MTA
diff --git a/src/mailman/docs/CONTRIBUTE.rst b/src/mailman/docs/CONTRIBUTE.rst
index d29784139..15c542e3e 100644
--- a/src/mailman/docs/CONTRIBUTE.rst
+++ b/src/mailman/docs/CONTRIBUTE.rst
@@ -1,5 +1,3 @@
-.. _start-here:
-
 =========================
 Contributing to Mailman 3
 =========================
@@ -7,40 +5,6 @@ Contributing to Mailman 3
 Copyright (C) 2008-2017 by the Free Software Foundation, Inc.
 
 
-Contact Us
-==========
-
-Contributions of code, problem reports, and feature requests are welcome.
-Please submit bug reports on the Mailman bug tracker at
-https://gitlab.com/mailman/mailman/issues (you need to have a login on GitLab
-to do so).  You can also send email to the mailman-developers@python.org
-mailing list, or ask on IRC channel ``#mailman`` on Freenode.
-
-
-Requirements
-============
-
-For the Core, Python 3.4 or newer is required.  It can either be the default
-'python3' on your ``$PATH`` or it can be accessible via the ``python3.4``,
-``python3.5``, or ``python3.6`` binary.  If your operating system does not
-include Python 3, see http://www.python.org for information about downloading
-installers (where available) and installing it from source (when necessary or
-preferred).  Python 2 is not supported by the Core.
-
-You may need some additional dependencies, which are either available from
-your OS vendor, or can be downloaded automatically from the `Python
-Cheeseshop`_.
-
-
-Documentation
-=============
-
-The documentation for Mailman 3 is distributed throughout the sources.  The
-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.
-
-
 How to contribute
 =================
 
@@ -52,6 +16,16 @@ of the GNU Mailman copyright.  If you'd like to jump start your copyright
 assignment, please contact the GNU Mailman `steering committee`_.
 
 
+Contact Us
+==========
+
+Contributions of code, problem reports, and feature requests are welcome.
+Please submit bug reports on the Mailman bug tracker at
+https://gitlab.com/mailman/mailman/issues (you need to have a login on GitLab
+to do so).  You can also send email to the mailman-developers@python.org
+mailing list, or ask on IRC channel ``#mailman`` on Freenode.
+
+
 Get the sources
 ===============
 
@@ -72,10 +46,10 @@ To run the Mailman test suite, just use the `tox`_ command::
 
     $ tox
 
-`tox` creates a virtual environment (virtualenv) for you, installs all the
+`tox` creates a virtual environment (virtualenv_) for you, installs all the
 dependencies into that virtualenv, and runs the test suite from that
 virtualenv.  By default it does not use the `--system-site-packages` so it
-downloads everything from the Cheeseshop.
+downloads everything from the `Python Cheeseshop`_.
 
 A bare ``tox`` command will try to run several test suites, which might take a
 long time, and/or require versions of Python or other components you might not
@@ -180,53 +154,6 @@ Then visit::
     build/sphinx/html/index.html
 
 
-Running Mailman 3
-=================
-
-What, you actually want to *run* Mailman 3?  Oh well, if you insist.
-
-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.
-
-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,
-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
-created by tox, e.g.::
-
-    $ .tox/py35-nocov/bin/mailman info
-
-
 Mailman Shell
 =============
 
@@ -272,7 +199,7 @@ via the REST client API.  This architecture makes it possible for users with
 other needs to adapt the web UI, or even replace it entirely, with a
 reasonable amount of effort.  However, as a core feature of Mailman, the web
 UI emphasizes usability over modularity at first, so most users should use the
-web UI described here.  Postorius is a Django_ application.
+web UI described here.  Postorius_ is a Django_ application.
 
 
 The Archiver
@@ -286,28 +213,33 @@ is appropriate for that archiver.  Summary, search, and retrieval of archived
 posts are handled by a separate application.
 
 A new archive UI called `HyperKitty`_, based on the `notmuch mail indexer`_
-was prototyped at the PyCon 2012 sprint by Toshio Kuratomi.  The HyperKitty
+was prototyped at the `Pycon 2012 sprint`_ by Toshio Kuratomi.  The HyperKitty
 archiver is very loosely coupled to Mailman 3 core.  In fact, any email
 application that speaks LMTP or SMTP will be able to use HyperKitty.
 HyperKitty is also a Django application.
 
 
+REST API Python bindings
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mailman 3 provides a REST API for administrative purposes, and this is used by
+both HyperKitty and Postorius.  You can of course use any HTTP client to speak
+to it, but we provide official Python bindings (for both Python 2 and 3) in a
+package we call `mailman.client`_.
+
+
+.. _`merge requests`: https://gitlab.com/mailman/mailman/merge_requests
+.. _`bug reports`: https://gitlab.com/mailman/mailman/issues
+.. _`copyright assignment`: https://www.fsf.org/licensing/assigning.html/?searchterm=copyright%20assignment
+.. _`steering committee`: mailto:mailman-cabal@python.org
+.. _tox: https://testrun.org/tox/latest/
+.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
 .. _`Postorius`: https://gitlab.com/mailman/postorius
-.. _`HyperKitty`: https://gitlab.com/mailman/hyperkitty
 .. _`Django`: http://djangoproject.org/
-.. _`REST client module`: https://gitlab.com/mailman/mailmanclient
-.. _`Five Minute Guide the Web UI`: WebUIin5.html
-.. _`blog post`: http://wiki.list.org/display/DEV/A+5+minute+guide+to+get+the+Mailman+web+UI+running
+.. _`HyperKitty`: https://gitlab.com/mailman/hyperkitty
 .. _`notmuch mail indexer`: http://notmuchmail.org
-.. _`five minute guide to Hyperkitty`: ArchiveUIin5.html
+.. _`mailman.client`: https://gitlab.com/mailman/mailmanclient
 .. _`Pycon 2012 sprint`: https://us.pycon.org/2012/community/sprints/projects/
 .. _`Python Cheeseshop`: http://pypi.python.org/pypi
 .. _`virtualenv`: http://www.virtualenv.org/en/latest/
 .. _`pyvenv`: https://docs.python.org/3/library/venv.html
-.. _`Mailman 3 Core documentation`: https://mailman.readthedocs.io
-.. _tox: https://testrun.org/tox/latest/
-.. _`merge requests`: https://gitlab.com/mailman/mailman/merge_requests
-.. _`bug reports`: https://gitlab.com/mailman/mailman/issues
-.. _`copyright assignment`: https://www.fsf.org/licensing/assigning.html/?searchterm=copyright%20assignment
-.. _`steering committee`: mailto:mailman-cabal@python.org
-.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
diff --git a/src/mailman/docs/INSTALL.rst b/src/mailman/docs/INSTALL.rst
new file mode 100644
index 000000000..8a4722190
--- /dev/null
+++ b/src/mailman/docs/INSTALL.rst
@@ -0,0 +1,120 @@
+====================
+Installing Mailman 3
+====================
+
+Copyright (C) 2008-2017 by the Free Software Foundation, Inc.
+
+
+Requirements
+============
+
+For the Core, Python 3.4 or newer is required.  It can either be the default
+'python3' on your ``$PATH`` or it can be accessible via the ``python3.4``,
+``python3.5``, or ``python3.6`` binary.  If your operating system does not
+include Python 3, see http://www.python.org for information about downloading
+installers (where available) and installing it from source (when necessary or
+preferred).  Python 2 is not supported by the Core.
+
+You may need some additional dependencies, which are either available from
+your OS vendor, or can be downloaded automatically from the `Python
+Cheeseshop`_.
+
+
+Documentation
+=============
+
+The documentation for Mailman 3 is distributed throughout the sources.  The
+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.
+
+
+Get the sources
+===============
+
+The Mailman 3 source code is version controlled using Git. You can get a
+local copy by running this command::
+
+    $ git clone https://gitlab.com/mailman/mailman.git
+
+or if you have a GitLab account and prefer ssh::
+
+    $ git clone git@gitlab.com:mailman/mailman.git
+
+
+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.
+
+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,
+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
+created by tox, e.g.::
+
+    $ .tox/py35-nocov/bin/mailman info
+
+
+Mailman Shell
+=============
+
+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
+``mailman.testing``.  For example, to use ``dump_list`` you first need to
+import it from the ``mailman.testing.documentation`` module.
+
+.. Of course, *this* doctest doesn't have these preloaded...
+   >>> from zope.component import getUtility
+   >>> from mailman.interfaces.listmanager import IListManager
+
+The shell automatically initializes the Mailman system, loads all the
+available interfaces, and configures the `Zope Component Architecture`_ (ZCA)
+which is used to access all the software components in Mailman.  So for
+example, if you wanted to get access to the list manager component, you could
+do::
+
+    $ mailman shell
+    Welcome to the GNU Mailman shell
+
+    >>> 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
diff --git a/src/mailman/docs/INTRODUCTION.rst b/src/mailman/docs/INTRODUCTION.rst
index b058c3193..e62dae183 100644
--- a/src/mailman/docs/INTRODUCTION.rst
+++ b/src/mailman/docs/INTRODUCTION.rst
@@ -1,3 +1,5 @@
+.. _start-here:
+
 ================================================
 Mailman - The GNU Mailing List Management System
 ================================================