basic docs

diff --git a/doc/pergamon.mdwn b/doc/pergamon.mdwn
new file mode 100644 (file)
index 0000000..887b67b
--- /dev/null
+++ b/doc/pergamon.mdwn
@@ -0,0 +1,22 @@
+Discuss was originally designed as a bulletin board system, but is now most commonly used at MIT for mailing list archiving. Pergamon is SIPB's self-service Discuss server. For more information on using discuss, you can see [SIPB's documentation](http://stuff.mit.edu/afs/sipb/project/www/discuss/discuss.html) ([DVI](http://stuff.mit.edu/afs/sipb/project/doc/current/discuss.dvi)). IS&T's [diswww](http://diswww.mit.edu/) service also provides a fairly self-explanatory (if you know the hostname and meeting name) web interface to Discuss.
+
+## Creating a Discuss archive
+
+The simplest way to create a private Discuss archive on Pergamon is to simply run
+
+    athrun adehnert make-discuss-archive listname desc acl
+
+Arguments:
+
+* `listname` should be the name of the Moira list you would like to archive.
+* `desc` should be a short (a couple word) description of the list, which will be used as the Discuss meeting's "long name" -- for example, "scripts.mit.edu administration archive".
+* `acl` should be the name of a Moira/AFS group (pass the `-G` flag to `blanche`) to sync. Pergamon does not currently support ongoing AFS sync, so you will need to manually resync the ACL (see below) when you update the list.
+
+## Relevant commands
+
+The `make-discuss-archive` script is fairly simple, and just shells out to `remctl` and `blanche`, so you can run the underlying commands yourself if you prefer:
+
+* `remctl pergamon discuss make-private-meeting "$list" "$desc"` will create a meeting that only you have read access to
+* `remctl pergamon discuss make-public-meeting "$list" "$desc"` will create a meeting that anybody can read
+* `remctl pergamon discuss set-read-acl "$list" "$acl"` will sync read access to the `$list` meeting with the Moira/AFS group `$acl`. You can always set this command to run from a cronjob if you wish, or just run it manually when you update the ACL group. (In the glorious future, Pergamon may gain support for doing this automatically, but we haven't written that yet. If you want to do so, let us know -- pergamon AT mit.edu.)
+* Pergamon will add anything sent to `$list-mtg@pergamon.mit.edu` to the discuss archive. If you want to archive a Mailman or non-MIT list, you can just add that address to your list. The script runs `blanche "$list" -a "$list-mtg@pergamon.mit.edu"` to do that for you.