Some updates to the documentation in preparation for alpha 7.

4 files changed, 44 insertions, 26 deletions

diff --git a/README.txt b/README.txt
index b1b2d8228..d0f2a7377 100644
--- a/README.txt
+++ b/README.txt
@@ -2,7 +2,7 @@
 Mailman - The GNU Mailing List Management System
 ================================================
 
-Copyright (C) 1998-2010 by the Free Software Foundation, Inc.
+Copyright (C) 1998-2011 by the Free Software Foundation, Inc.
 
 This is GNU Mailman, a mailing list management system distributed under the
 terms of the GNU General Public License (GPL) version 3 or later.  The name of
@@ -11,9 +11,9 @@ case second `m'.  Any other spelling is incorrect.
 
 Mailman is written in Python which is available for all platforms that Mailman
 is supported on, including GNU/Linux and most other Unix-like operating
-systems (e.g. Solaris, *BSD, MacOSX, etc.).  It does not run on Windows,
-although web and mail clients on any platform should be able to interact with
-Mailman just fine.
+systems (e.g. Solaris, *BSD, MacOSX, etc.).  Mailman is not supported on
+Windows, although web and mail clients on any platform should be able to
+interact with Mailman just fine.
 
 The Mailman home page is:
 
diff --git a/src/mailman/docs/MTA.txt b/src/mailman/docs/MTA.txt
index 2bccce333..f541d3838 100644
--- a/src/mailman/docs/MTA.txt
+++ b/src/mailman/docs/MTA.txt
@@ -48,7 +48,7 @@ You need to tell Mailman that you are using the Postfix mail server.  In your
 
 Some of these settings are already the default, so take a look at Mailman's
 `src/mailman/config/schema.cfg` file for details.  You'll need to change the
-`lmtp_host` and `smtp_post` to the appropriate host names of course.
+`lmtp_host` and `smtp_host` to the appropriate host names of course.
 Generally, Postfix will listen for incoming SMTP connections on port 25.
 Postfix will deliver via LMTP over port 24 by default, however if you are not
 running Mailman as root, you'll need to change this to a higher port number,
diff --git a/src/mailman/docs/README.txt b/src/mailman/docs/README.txt
index d912a680f..b7a247de4 100644
--- a/src/mailman/docs/README.txt
+++ b/src/mailman/docs/README.txt
@@ -53,8 +53,8 @@ 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 now being primarily maintained by Mark Sapiro and Tokio Kikuchi.  Barry
-Warsaw is the lead developer on Mailman 3.
+2.1 is primarily maintained by Mark Sapiro and Tokio Kikuchi.  Barry Warsaw is
+the lead developer on Mailman 3.
 
 
 Help
@@ -90,8 +90,7 @@ Mailman 3.0 requires `Python 2.6`_ or newer.
 .. _`Getting Started`: START.html
 .. _Python: http://www.python.org
 .. _FAQ: http://wiki.list.org/display/DOC/Frequently+Asked+Questions
-.. _`Python 2.6`: http://www.python.org/download/releases/2.6.2/
-.. _`ALPHA.txt`: ALPHA.html
+.. _`Python 2.6`: http://www.python.org/download/releases/2.6.6/
 
 
 Table of Contents
@@ -100,7 +99,11 @@ Table of Contents
 .. toctree::
     :glob:
 
-    *
+    START
+    MTA
+    NEWS
+    STYLEGUIDE
+    ACKNOWLEDGMENTS
     ../bin/docs/*
     ../commands/docs/*
     ../model/docs/*
diff --git a/src/mailman/docs/START.txt b/src/mailman/docs/START.txt
index 3c9e30280..678122205 100644
--- a/src/mailman/docs/START.txt
+++ b/src/mailman/docs/START.txt
@@ -22,39 +22,52 @@ Using the Alpha
 
 Python 2.6 is required.  It can either be the default 'python' on your $PATH
 or it can be accessible via the 'python2.6' binary.  See http://www.python.org
-for details on getting Python 2.6.
+for details on getting Python 2.6.  Mailman works just fine with Python 2.7,
+but Python 3 is not yet supported.
 
 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 2.6 and an internet connection
-to get all the other Mailman 3 dependencies.  Here are the commands to
-build everything::
+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::
 
-    % python2.6 bootstrap.py
+    % python bootstrap.py
     % bin/buildout
 
 Now you can run the test suite via::
 
-    % bin/test
+    % bin/test -vv
 
 You should see no failures.
 
-At this point you can 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.
+Build the online docs by running::
+
+    % bin/docs
+
+(You will get warnings which you can safely ignore.)  Then visit
+
+    parts/docs/mailman/build/mailman/docs/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.
 
 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 via the `lazr.config`_
 package which is really just a fancy ini-style configuration system.
 
-For now though, start by looking through ``src/mailman/config/schema.cfg``.
-Create a file for your overrides; it can be called anything and can live
-anywhere, but I like to call it ``mailman.cfg``.  For any value in
-``schema.cfg`` you want to override, just add a section header (the
-square-bracketed names) and then the key/value pair you want to override.
+``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.
@@ -74,8 +87,10 @@ Try ``bin/mailman --help`` for more details.  You can use the commands
 ``bin/mailman start`` to start the queue runner daemons, and of course
 ``bin/mailman stop`` to stop them.
 
-There is no web u/i right now.  Contributions are welcome!
+The `web ui`_ is being developed as a separate, Django-based project.  For
+now, all configuration happens via the command line and REST API.
 
 
 .. _`zc.buildout`: http://pypi.python.org/pypi/zc.buildout
 .. _`lazr.config`: http://pypi.python.org/pypi/lazr.config
+.. _`web ui`: https://launchpad.net/mailmanweb