Some reorganization.

1 files changed, 52 insertions, 32 deletions

diff --git a/doc/mailman-install.tex b/doc/mailman-install.tex
index 84c9c2f7..16484737 100644
--- a/doc/mailman-install.tex
+++ b/doc/mailman-install.tex
@@ -1245,6 +1245,38 @@ Bollow has written about Mailman and qmail, available here:
 
     \url{http://mailman.cis.to/qmail-verh/}
 
+\section{Review your site defaults\label{customizing}}
+
+Mailman has a large number of site-wide configuration options which you should
+now review and change according to your needs.  Some of the options control
+how Mailman interacts with your environment, and other options select defaults
+for newly created lists\footnote{In general, changing the list defaults
+described in this section will not affect any already created lists.  To make
+changes after a list has been created, use the web interface or the command
+line scripts, such as \program{bin/withlist} and \program{bin/config_list}.}.
+There are system tuning parameters and integration options.
+
+The full set of site-wide defaults lives in the
+\file{\var{\$prefix}/Mailman/Defaults.py} file, however you should
+\strong{never} modify this file!  Instead, change the \file{mm_cfg.py} file in
+that same directory.  You only need to add values to \file{mm_cfg.py} that are
+different than the defaults in \file{Defaults.py}, and future Mailman upgrades
+are guaranteed never to touch your \file{mm_cfg.py} file.
+
+The \file{Defaults.py} file is documented extensively, so the options are not
+described here.  The \file{Defaults.py} and \file{mm_cfg.py} are both
+\ulink{Python}{http://www.python.org} files so valid Python syntax must be
+maintained or your Mailman installation will break.
+
+\begin{notice}[note]
+Do \strong{not} change the \var{HOME_DIR} or \var{MAILMAN_DIR} variables.
+These are set automatically by the \program{configure} script, and you will
+break your Mailman installation by if you change these.
+\end{notice}
+
+You should make any changes to \file{mm_cfg.py} using the account you
+installed Mailman under in the \ref{building} section.
+
 \section{Create a site-wide mailing list}
 
 After you have completed the integration of Mailman and your mail server, you
@@ -1377,47 +1409,35 @@ in the \file{mm_cfg.py} file:
 You will want to run the \program{bin/fix_url.py} to change the domain of any
 existing lists.
 
-\section{Customize Mailman\label{customizing}}
+\section{Create the site password}
 
-Now that Mailman is all set up, there are a few site-wide configurations you
-can make before you start creating mailing lists.  You should do these steps
-using the account you installed Mailman under in the \ref{building} section.
+There are two site-wide passwords that you can create from the command line,
+using the \program{bin/mmsitepass} script.  The first is the ``site password''
+which can be used anywhere a password is required in the system.  The site
+password will get you into the administration page for any list, and it can be
+used to log in as any user.  Think \code{root} for a Unix system, so pick this
+password wisely!
 
-\begin{itemize}
-\item The file \file{\var{\$prefix/Mailman/Defaults.py}} contains a number of
-      defaults for your installation.  If any of these are incorrect, override
-      them in \file{\var{\$prefix}/Mailman/mm_cfg.py}, \strong{not} in the
-      \file{Defaults.py} file!  See the comments in \file{Defaults.py} for
-      details.  Once a list is created, editing many of these variables will
-      have no effect.  At that point, you'll need to configure your lists
-      through the web administration interface or through the command line
-      scripts \program{bin/withlist} and \program{bin/config_list}.
-
-      The install process will never overwrite an existing \file{mm_cfg.py}
-      file so you can freely make changes to this file.
-
-      \begin{notice}[note]
-      Do \strong{not} change the \var{HOME_DIR} or \var{MAILMAN_DIR}
-      variables.  These are set automatically by the \program{configure}
-      script, and you will break your Mailman installation by if you change
-      these.
-      \end{notice}
-\item Create the site password.  Use this command:
+The second password is a site-wide ``list creator'' password.  You can use
+this to delegate the ability to create new mailing lists without providing all
+the privileges of the site password.  Of course, the owner of the site
+password can also create new mailing lists, but the list creator password is
+limited to just that special role.
+
+To set the site password, use this command:
 
 \begin{verbatim}
     % $prefix/bin/mmsitepass <your-site-password>
 \end{verbatim}
 
-    This password can be used anywhere that individual user or mailing list
-    administrator passwords are required, giving the mailman site
-    administrator the ability to adjust these things when necessary.
+To set the list creator password, use this command:
 
-    You may also want to create a password for the site-wide ``list creator''
-    role.  The list creator is someone other than the site administrator who
-    has privileges to create and remove lists through the web interface.  Use
-    the \programopt{-c} option to \program{mmsitepass} to set this.
+\begin{verbatim}
+    % $prefix/bin/mmsitepass -c <list-creator-password>
+\end{verbatim}
 
-\end{itemize}
+It is okay not to set a list creator password, but you probably do want a site
+password.
 
 \section{Create your first mailing list}