4 files changed, 303 insertions, 20 deletions

diff --git a/src/mailman/docs/ArchiveUIin5.rst b/src/mailman/docs/ArchiveUIin5.rst
new file mode 100644
index 000000000..58b48cd3d
--- /dev/null
+++ b/src/mailman/docs/ArchiveUIin5.rst
@@ -0,0 +1,97 @@
+=====================================
+Set up the archive ui in five minutes
+=====================================
+
+The `hyperkitty`_ application aims at providing an interface to visualize and
+explore Mailman archives.
+
+This is a `Django`_ project.
+
+Requirements
+============
+
+- A mail archive in `maildir format`_ (no, you don't need a running Mailman
+  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
+  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
+  message archive itself.  (Since the archive is in `maildir format`_, any
+  modern MTA or MDA can build one for you.)
+
+
+Get it running (under virtualenv):
+----------------------------------
+
+It is generally a good idea to use `virtualenv`_ to create a stable
+environment for your Python applications.
+
+- Create the virtualenv::
+
+    % virtualenv mailman3
+
+- Activate the virtualenv::
+
+    % cd mailman3
+    % source bin/activate
+
+You don't *have* to use virtualenv, though, and if you don't want to, just
+omit the preceding steps.  Continue with these steps.
+
+- Install Django and dependencies::
+
+    % easy_install django
+    % easy_install bunch
+
+- Install notmuch -- these are bindings that come with the notmuch C library.
+  The easiest way is probably to install them for your OS vendor and then
+  symlink them into the virtualenv similar to this::
+
+    % yum install -y python-notmuch
+
+- Note: on a multiarch system like Fedora, the directories may be lib64 rather
+  than lib on 64 bit systems.  Next::
+
+    % cd lib/python2.7/site-packages
+    % ln -s /usr/lib/python2.7/site-packages/notmuch .
+
+- Note: this is the version of notmuch I tested with; others may work::
+
+    % ln -s /usr/lib/python2.7/site-packages/notmuch-0.11-py2.7.egg-info .
+
+- Install the hyperkitty sources::
+
+    % git clone http://ambre.pingoured.fr/cgit/hyperkitty.git/
+
+
+Running hyperkitty
+------------------
+
+- Start it::
+
+    % cd hyperkitty
+
+- Put the static content where it should be::
+
+    % python manage.py collectstatic
+
+- Run the Django server::
+
+    % python manage.py runserver
+
+
+.. _`hyperkitty`: https://launchpad.net/hyperkitty
+.. _`Django`: http://djangoproject.org/
+.. _`notmuch mail indexer`: http://notmuchmail.org
+.. _`bunch`: http://pypi.python.org/pypi/bunch
+.. _`Xapian`: http://xapian.org/
+.. _`maildir format`: http://en.wikipedia.org/wiki/Maildir
+.. _`mbox format`: http://en.wikipedia.org/wiki/Mbox
+.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
diff --git a/src/mailman/docs/NEWS.rst b/src/mailman/docs/NEWS.rst
index 6df96a269..48736b518 100644
--- a/src/mailman/docs/NEWS.rst
+++ b/src/mailman/docs/NEWS.rst
@@ -30,6 +30,11 @@ Configuration
    circumstances a message destined for a specific archiver should have its
    `Date:` header clobbered.  (LP: #963612)
 
+Documentation
+-------------
+ * Some additional documentation on related components such as Postorius and
+   hyperkitty have been added, given by Stephen J Turnbull.
+
 
 3.0 beta 1 -- "The Twilight Zone"
 =================================
diff --git a/src/mailman/docs/START.rst b/src/mailman/docs/START.rst
index ab2717956..cd7b5247d 100644
--- a/src/mailman/docs/START.rst
+++ b/src/mailman/docs/START.rst
@@ -2,39 +2,61 @@
 Getting started with GNU Mailman
 ================================
 
-Copyright (C) 2008-2011 by the Free Software Foundation, Inc.
+Copyright (C) 2008-2012 by the Free Software Foundation, Inc.
 
 
-Alpha Release
-=============
+Beta Release
+============
 
-The Mailman 3 alpha releases are being provided to give developers and other
-interested people an early look at the next major version.  As such, some
-things may not work yet.  Your participation is encouraged.  Your feedback and
-contributions are welcome.  Please submit bug reports on the Mailman bug
+This is a beta release.  The developers believe it has sufficient
+functionality to provide full services to a mailing list, but it is not ready
+for production yet.  Interfaces and administration may differ substantially
+from the alpha series, but changes should be incremental going forward from
+beta 1.  Changes from the alpha series will be described in notes to the main
+text.
+
+The Mailman 3 beta releases are being provided to give developers and other
+interested people an early look at the next major version, and site
+administrators a chance to prepare for an eventual upgrade.  The core list
+management and post distribution functionality is now complete.  However,
+unlike Mailman 2 whose web interface and archives were tightly integrated with
+the core, Mailman 3 exposes a REST administrative interface to the web,
+communicates with archivers via decoupled interfaces, and leaves summary,
+search, and retrieval of archived messages to a separate application (a simple
+implementation is provided).  As of beta 1 the web interface and archiver are
+still at an early stage of development.  As such, some things may not work.
+
+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
 mailman-developers@python.org mailing list.
 
 
-Using the Alpha
-===============
+Requirements
+============
 
 Python 2.6 or 2.7 is required.  It can either be the default 'python' on your
 $PATH or it can be accessible via the ``python2.6`` or ``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.
 
-
-Building Mailman 3
-==================
+In this documentation, a bare ``python`` refers to the python used to invoke
+``bootstrap.py``, which might be ``python2.6`` or ``python2.7``, as well as
+the system ``python`` or an absolute path.
 
 Mailman 3 is now based on the `zc.buildout`_ infrastructure, which greatly
 simplifies building and testing Mailman.
 
-You do not need anything other than Python and an internet connection to get
-all the other Mailman 3 dependencies.  Here are the commands to build
-everything::
+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
+internet connection.  Also the `web UI`_ and `archive UI`_ are distributed and
+installed separately.
+
+
+Building Mailman 3
+==================
+
+Here are the commands to build everything in core Mailman::
 
     % python bootstrap.py
     % bin/buildout
@@ -50,16 +72,16 @@ You should see no failures.
 
 Build the online docs by running::
 
-    % bin/docs
+    % python setup.py build_sphinx
 
-(You might get warnings which you can safely ignore.)  Then visit
+(You might get warnings which you can safely ignore.)  Then visit::
 
-    parts/docs/mailman/build/mailman/docs/README.html
+    build/sphinx/html/README.html
 
 in your browser to start reading the documentation.  Or you can just read the
 doctests by looking in all the 'doc' directories under the 'mailman' package.
 Doctests are documentation first, so they should give you a pretty good idea
-how various components of Mailman 3 works.
+how various components of Mailman 3 work.
 
 
 Running Mailman 3
@@ -88,6 +110,7 @@ The first existing file found wins.
  * ``./mailman.cfg``
  * ``~/.mailman.cfg``
  * ``/etc/mailman.cfg``
+ * ``argv[0]/../../etc/mailman.cfg``
 
 Run the ``bin/mailman info`` command to see which configuration file Mailman
 will use, and where it will put its database file.  The first time you run
@@ -102,6 +125,51 @@ The `web ui`_ is being developed as a separate, Django-based project.  For
 now, all configuration happens via the command line and REST API.
 
 
+Mailman Web UI
+--------------
+
+The Mailman 3 web UI, called *Postorius*, interfaces to core Mailman engine
+via the REST client API.  It is expected that this architecture will make 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 will emphasize usability over modularity at first, so most
+users should use the web UI described here.
+
+Postorius was prototyped at the `Pycon 2012 sprint`_, so it is "very alpha" as
+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
+Mailman wiki.  (Check the `blog post`_ for the most recent version!)
+
+
+The List 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
+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.
+
+A new `archive UI`_ called Hyperkitty, based on the `notmuch mail indexer`_
+and `Django`_, was prototyped at the PyCon 2012 sprint by Toshio Kuratomi, and
+like the web UI it is also in early alpha as of Mailman 3 beta 1.  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.
+
+A `five minute guide to hyperkitty`_ is based on Toshio Kuratomi's README.
+
+
 .. _`zc.buildout`: http://pypi.python.org/pypi/zc.buildout
 .. _`lazr.config`: http://pypi.python.org/pypi/lazr.config
-.. _`web ui`: https://launchpad.net/mailmanweb
+.. _`Postorius`: https://launchpad.net/postorius
+.. _`archive UI`: https://launchpad.net/hyperkitty
+.. _`Django`: http://djangoproject.org/
+.. _`REST client module`: https://launchpad.net/mailman.client
+.. _`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
+.. _`notmuch mail indexer`: http://notmuchmail.org
+.. _`five minute guide to hyperkitty`: ArchiveUIin5.html
+.. _`Pycon 2012 sprint`: https://us.pycon.org/2012/community/sprints/projects/
diff --git a/src/mailman/docs/WebUIin5.rst b/src/mailman/docs/WebUIin5.rst
new file mode 100644
index 000000000..5000de9ad
--- /dev/null
+++ b/src/mailman/docs/WebUIin5.rst
@@ -0,0 +1,113 @@
+================================
+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 `Bazaar`_
+version control system installed on your system.  Mailman and mailman.client
+need 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`_.
+
+.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
+.. _`Here is a brief HOWTO`: ./ArchiveUIin5.html#get-it-running-under-virtualenv
+.. _`Bazaar`: http://bazaar.canonical.com/en/
+
+
+GNU Mailman 3
+=============
+
+First download the latest revision of Mailman 3 from Launchpad.
+::
+
+  $ bzr branch lp:mailman
+
+Install and test::
+
+  $ cd mailman
+  $ python bootstrap.py
+  $ bin/buildout
+  $ bin/test
+
+If you get no errors you can now start Mailman::
+
+  $ bin/mailman start
+  $ cd ..
+
+At this point Mailman will not send nor receive any real emails.  But that's
+fine as long as you only want to work on the components related to the REST
+client or the web ui.
+
+
+mailman.client (the Python bindings for Mailman's ReST API)
+===========================================================
+
+Download from Launchpad::
+
+  $ bzr branch lp:mailman.client
+
+Install in development mode to be able to change the code without working
+directly on the PYTHONPATH.
+::
+
+  $ cd mailman.client
+  $ sudo python setup.py develop
+  $ cd ..
+
+
+Django >= 1.3
+=============
+
+Postorius is a pluggable Django application.  Therefore you need to have
+Django (at least version 1.3) installed.
+::
+
+  $ wget http://www.djangoproject.com/download/1.3.1/tarball/ -O Django-1.3.1.tar.gz
+  $ tar xzf Django-1.3.1.tar.gz
+  $ cd Django-1.3.1
+  $ sudo python setup.py install
+  $ cd ..
+
+
+Postorius
+=========
+
+::
+
+  $ bzr branch lp:postorius
+  $ cd postorius
+  $ sudo python setup.py develop
+
+
+Start the development server
+============================
+
+::
+
+  $ cd dev_setup
+  $ python manage.py syncdb
+  $ 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.