Index: /trunk/cereal/Makefile
===================================================================
--- /trunk/cereal/Makefile	(revision 439)
+++ /trunk/cereal/Makefile	(revision 440)
@@ -31,5 +31,5 @@
 	mkdir -p build/upstream
 	ln -s ../.. build/upstream/cereal-$(VERSION)
-	(cd build/upstream && tar czf ../cereal_$(VERSION).tar.gz --exclude=.svn --exclude=*~ cereal-$(VERSION)/{fs,COPYING,Makefile})
+	(cd build/upstream && tar czf ../cereal_$(VERSION).tar.gz --exclude=.svn --exclude=*~ cereal-$(VERSION)/{fs,COPYING,Makefile,docs})
 	rm -f build/upstream/cereal-$(VERSION)
 
Index: /trunk/cereal/TODO
===================================================================
--- /trunk/cereal/TODO	(revision 439)
+++ /trunk/cereal/TODO	(revision 440)
@@ -5,6 +5,4 @@
 - jamie doesn't want to do this.  jamie thinks timestamps are plenty
    "reasonable" as they are.  
-
-figure out what else the post{inst,rm} scripts need to be doing
 
 lock screen session from arbitrary execution
@@ -21,2 +19,4 @@
 
 bash completion
+
+create example "how to use cereal" file.
Index: /trunk/cereal/debian/changelog
===================================================================
--- /trunk/cereal/debian/changelog	(revision 439)
+++ /trunk/cereal/debian/changelog	(revision 440)
@@ -1,2 +1,9 @@
+cereal (0.4-1) unstable; urgency=low
+
+  * added more documentation
+  * NOT FOR RELEASE
+
+ -- Daniel Kahn Gillmor <dkg-debian.org@fifthhorseman.net>  Fri, 30 Mar 2007 02:28:06 -0400
+
 cereal (0.3-3) unstable; urgency=low
 
Index: /trunk/cereal/docs/reciprocal-serial-consoles.txt
===================================================================
--- /trunk/cereal/docs/reciprocal-serial-consoles.txt	(revision 440)
+++ /trunk/cereal/docs/reciprocal-serial-consoles.txt	(revision 440)
@@ -0,0 +1,40 @@
+Using Cereal for simple, reciprocal serial console access
+---------------------------------------------------------
+
+Here is a common way to set up cereal.
+
+The assumption here is that the second serial port on this machine
+(galago) is connected to the console of another host (grivet).
+
+## set up a group which can view the logs from grivet, but can't
+## necessarily attach:
+0 galago:~# addgroup grivetviewers
+Adding group `grivetviewers' (GID 1001) ...
+Done.
+
+## create a separate user account who will control grivet (and can attach):
+0 galago:~# adduser --ingroup grivetviewers --disabled-password --gecos 'grivet console controller,,,' grivetconsole
+Adding user `grivetconsole' ...
+Adding new user `grivetconsole' (1001) with group `grivetviewers' ...
+Creating home directory `/home/grivetconsole' ...
+Copying files from `/etc/skel' ...
+
+## set up access for that user with ssh keys (here we just use the
+## same keypairs that can already connect to root):
+0 galago:~# cat ~/.ssh/authorized_keys >> ~grivetconsole/.ssh/authorized_keys 
+
+## set up the cereal session itself:
+0 galago:~# cereal-admin create grivet /dev/ttyS1 115200 grivetconsole grivetviewers
+Created session 'grivet':
+--f grivet /dev/ttyS1 115200 grivetconsole grivetviewers
+0 galago:~# cereal-admin enable grivet
+Enabled session 'grivet'.
++-f grivet /dev/ttyS1 115200 grivetconsole grivetviewers
+0 galago:~# 
+
+
+Now, assuming that galago is running a console on its first serial
+port (ttyS0), connect grivet's second serial port to galago's console
+and perform the above operations on grivet, but with the names swapped
+around.
+
Index: /trunk/cereal/fs/usr/share/man/man1/cereal.1
===================================================================
--- /trunk/cereal/fs/usr/share/man/man1/cereal.1	(revision 439)
+++ /trunk/cereal/fs/usr/share/man/man1/cereal.1	(revision 440)
@@ -7,12 +7,29 @@
 .PP
 \fBcereal\fP is the client program to attach to a running cereal session.
-Without arguments, \fBcereal\fP will list the available sessions that the user is
-allowed to access.  Otherwise, the first argument should be the session name to
-attach to.
 .PP
-To detach from a session, detach the screen from the terminal with the screen
-detach key command ("C-a C-d" by default).
+\fBcereal attach foo\fP will attach to (take control of) a cereal session named "foo".
 .PP
-See `man screen' for more info on how to use screen while in the session. 
+\fBcereal follow foo\fP will follow (watch, without being able to
+intervene) a cereal session named "foo".  You can stop following a
+session by sending it a SIGINT (Ctrl+c).
+.PP
+\fBcereal list\fP will list the available sessions that the user is
+allowed to access.  The leading three characters in the list indicate:
+.TP
+\(bu
+whether the session is enabled (+) or not (-)
+.TP
+\(bu
+whether the user can attach to the session (a) or not (-)
+.TP
+\(bu
+whether the user can follow the session (a) or not (-)
+.PP
+To detach from an attached session, use the screen detach key command
+("C-a C-d" by default).
+.PP
+See
+.BR screen (1)
+for more info on how to use screen while in the session. 
 .PP
 The cereal system is outlined at: