New Mailman 2.0 documentation. Uses ht2html site generator, with the

MMGenerator style.  The ht2html tool isn't included here, but it's
available from

	http://www.wooz.org/users/barry/software/pyware.html

It's not completely filled in, but it's better than it was!

Note that we're checking in both the templates and the generated html
files, so distros contain the final documentation.

1 files changed, 219 insertions, 0 deletions

diff --git a/admin/www/admins.ht b/admin/www/admins.ht
new file mode 100644
index 000000000..31eae4f86
--- /dev/null
+++ b/admin/www/admins.ht
@@ -0,0 +1,219 @@
+Title: Site Administrator Documentation
+Links: links.h doco-links.h
+
+<h3>Site Administrator Documentation</h3>
+
+By definition, the site administrator has shell access to the Mailman
+installation, and the proper permissions for total control over
+Mailman at the site.  The site admin can edit the
+<code>Mailman/mm_cfg.py</code> configuration file, and can run the
+various and sundry command line scripts.
+
+<h3>Command line scripts</h3>
+
+This is a brief overview of the current crop of command line scripts
+available to the site administrator in the <code>bin</code> directory.
+For more details, run the script with the <code>--help</code> option,
+which will print out the usage synopsis.  <em>You must run these
+scripts from the bin directory in the Mailman installation location,
+usually <code>/home/mailman</code></em>.
+
+<dl>
+<dt><b>add_members</b>
+<dd>Use this script to mass add members to a mailing list.  Input
+    files are plain text, with one address per line.  Command line
+    options allow you to add the addresses as digest or regular
+    members, select whether various notification emails are sent, and
+    choose which list to add the members to.
+
+<dt><b>arch</b>
+<dd>Use this to rebuild a list's archive.  This script can't be used
+    to modify a list's raw mbox file, but once you've edited the mbox
+    file some other way, you can use this script to regenerate the
+    HTML version of the on-line archive.
+
+<dt><b>check_db</b>
+<dd>Use this script to check the integrity of a list's
+    <code>config.db</code> and <code>config.db.last</code> database
+    files.
+
+<dt><b>check_perms</b>
+<dd>Use this script to check, and optionally fix, the permissions of
+    the various files in a Mailman installation.
+
+<dt><b>clone_member</b>
+<dd>Use this script to <em>clone</em> an address on a particular list
+    into different address.  This is useful when someone is changing
+    email addresses and wants to keep all their old configuration
+    options.  Eventually members will be able to do their own cloning,
+    but for now, only the site administrator can do this.  Command
+    line options let you remove the old address, clone addresses in
+    the list managers addresses, etc.
+
+<dt><b>config_list</b>
+<dd>This is a very powerful script which lets you view and modify a
+    list's configuration variables from the command line.  E.g.  you
+    can dump out all the list options into a plain text file (actually
+    a valid Python file!), complete with comments explaining each
+    variable.  Or you can apply the configuration from such a file to
+    a particular list.
+
+    <p>Where this might be useful is if you wanted to change the
+    <code>web_page_url</code> attribute on every list.  You could
+    create a file containing only the line
+
+<blockquote>
+<pre>
+web_page_url = 'http://www.mynewsite.com/mailman-relocated/'
+</pre>
+</blockquote>
+
+    and then feed this file back to <code>config_list</code> for every
+    list on your system.  <code>config_list</code> only sets the
+    list variables that it finds in the input file.
+
+<dt><b>digest_arch</b>
+<dd>This script is deprecated.
+
+<dt><b>dumpdb</b>
+<dd>This script dumps the plain text representation for any <code>.db</code>
+    database file.  These files usually contain Python marshaled
+    dictionaries, and can be found in the <code>qfiles</code>
+    directory, the <code>lists/<em>listname</em></code> directory,
+    etc.
+
+<dt><b>find_member</b>
+<dd>Use this script to search all the lists, or some subset of lists,
+    for an address matching a regular expression.  command line
+    options let you also search the list managers as well.
+
+<dt><b>list_lists</b>
+<dd>List all, or some subset of, the mailing lists in the system.
+
+<dt><b>list_members</b>
+<dd>List the members of a mailing list.  Command line options let you
+    print just the regular or just the digest members, print the
+    case-preserved addresses of the members, etc.
+
+<dt><b>mmsitepass</b>
+<dd>Use this script to set the site password, which can be used any
+    where in the system a list or user password can be used.
+    Essentially, the site password trumps any other password, so
+    choose wisely!
+
+<dt><b>move_list</b>
+<dd>Use this script when you move Mailman to a new installation location.
+
+<dt><b>newlist</b>
+<dd>Use this script to create new mailing lists.
+
+<dt><b>remove_members</b>
+<dd>Use this list to remove members from a mailing list.
+
+<dt><b>rmlist</b>
+<dd>Use this script to remove a mailing list.  By default, a list's
+    archives are not removed unless the <code>--archives</code> option
+    is given.
+
+<dt><b>sync_members</b>
+<dd>Use this to synchronize mailing lists in a list's database with a
+    plain text file of addresses, similar to what is used for
+    <code>add_members</code>.  In a sense, this script combines the
+    functionality of <code>add_members</code> and
+    <code>remove_members</code>.  Any addresses in the file that are
+    not present in the list roster are added, and any addresses in the
+    roster that are not present in the file are removed.
+
+    <p>Command line options let you send various notification emails,
+    preview the changes, etc.
+
+<dt><b>update</b>
+<dd>Don't use this script manually; it is used as part of the
+    installation and upgrade procedures.
+
+<dt><b>version</b>
+<dd>Prints the Mailman version number.
+
+<dt><b>withlist</b>
+<dd>This is the most powerful and flexible script in Mailman.  With it
+    you can do all manner of programmatic changes to mailing lists, or
+    look at and interactively inspect almost any aspect of Mailman.
+    By default, you run this using Python's interactive prompt, like
+    so:
+
+<blockquote>
+<pre>
+% cd /home/mailman
+% python -i bin/withlist mylist
+Loading list: mylist (unlocked)
+>>> 
+</pre>
+</blockquote>
+
+    Here you see that you're left at the Python prompt after the list
+    has been loaded and instantiated.  Note that without the
+    <code>--lock</code> option, the list is not locked.  List must be
+    locked if you plan to make modifications to any attributes (and
+    they must be explicitly saved, as <code>withlist</code> does not
+    automatically save changes to list objects).
+
+    <p>At the prompt, the global object <em>m</em> is the instantiated
+    list object.  It's a Python instance so you can do all the normal
+    things to it, view or change attributes, or make method calls on
+    it.
+
+    <p>Have a look also at the <code>--run</code> option, which lets
+    you put your programmatic changes into a Python module (file) and
+    run that module over any mailing list you want.  This makes
+    <code>withlist</code> essentially a framework for easily adding
+    your own list-specific command line scripts.
+</dl>
+
+<h3>Cron scripts</h3>
+
+Mailman comes with a number of scripts that are typically only run by
+cron.  However, it is generally okay for the site administrator to run
+these scripts manually, say to force a sending of accumulated digests,
+or to mail out member passwords, etc.  You generally run these by
+invoking the Python executable on them, like so:
+
+<blockquote>
+<pre>
+% cd /home/mailman
+% python -S cron/senddigests
+</pre>
+</blockquote>
+
+The <code>-S</code> option is an optimization and (minor) security
+recommendation; it inhibits Python's implicit <code>import site</code>
+on initialization.  Not all of these scripts support the
+<code>--help</code> option.  Here is a brief description of what the
+cron scripts do:
+
+<dl>
+<dt><b>bumpdigests</b>
+<dd><em>Bumps</em> the digest volume numbers for the specified lists.
+    Resets the issue number to 1.
+
+<dt><b>checkdbs</b>
+<dd>Checks for ending list requests (posts and subscriptions) and
+    mails the list manager if there are any.
+
+<dt><b>gate_news</b>
+<dd>Polls the NNTP servers for messages and forwards any new messages
+    to their mailing list gateways.
+
+<dt><b>mailpasswds</b>
+<dd>Sends the password reminder emails to all users and all mailing lists.
+
+<dt><b>nightly_gzip</b>
+<dd>Regenerates the Pipermail <code>gzip</code>'d flat archive files.
+
+<dt><b>qrunner</b>
+<dd>This is the primary cron script for processing messages in
+    Mailman's queue directory <code>qfiles</code>.
+
+<dt><b>senddigests</b>
+<dd>Sends all accumulated digests.
+
+</dl>