Index: doc/advanced.txt
===================================================================
--- doc/advanced.txt	(revision 675ce49ec986337de5dffba27f20b2a1e23fb442)
+++ doc/advanced.txt	(revision 675ce49ec986337de5dffba27f20b2a1e23fb442)
@@ -0,0 +1,108 @@
+                     ========================
+                     Owl Advanced Users Guide
+                     ========================
+
+
+=========================
+Section X: CUSTOM FILTERS
+=========================
+
+
+==========================
+Section X: THE CONFIG FILE
+==========================
+
+=======================
+Section X: KEY BINDINGS
+=======================
+
+
+=========================
+Section X: COMMAND ALISES
+=========================
+
+
+=================
+Section X: STYLES
+=================
+
+
+- - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+
+For example, the following
+command will create a filter called 'mail' that maches any messages
+sent to the zephyr class 'mail':
+
+     filter mail class ^mail$
+
+The first argument after the filter command specifies the name of the
+filter to be created.  The text after that indicates that matching
+messages must have the zephyr class "mail".  For help understanding
+the '^' and '$' characters, consult a reference on regular
+expressions.  Note that all pattern matching in Owl is
+case-insensitive.
+
+The message fields that can be used in a filter command include:
+
+     sender        message sender
+     recipient     message recipient
+     class         zephyr class name
+     instance      zephyr instance name
+     opcode        zephyr opcode
+     realm         zephyr realm
+     body          message body
+     type          message type ('zephyr', 'aim', 'admin')
+     direction     either 'in' 'out' or 'none'\n"
+     login         either 'login' 'logout' or 'none'\n" 
+
+You can also use the operators 'and' 'or' and 'not' as well as the
+values 'true' and 'false'.  Parentheses can be used to group
+expressions, though there must be spaces present before and after all
+parenthesis.  For example:
+
+   filter myfilt ( class ^foo$ ) or ( class ^quux$ and instance ^bar$ )
+
+If you define a filter using a filter name that already exists, it
+will overwrite the existing filter.  This can be a useful way to
+override the built-in filters.
+
+
+==========================
+Section 6: THE CONFIG FILE
+==========================
+
+*** WARNING: This interface may change substantially in the near future ***
+
+This file is interpreted by the perl interpreter.
+If you wish to execute an owl command use the
+function owl::command().  i.e.
+
+     owl::command("set zsigproc \"/mit/kretch/bin/getzsig foo\"");
+
+will set the owl variable zsigproc.  Note that commands will currently
+be executed in order after the called configuration subroutine exits.
+
+Subroutines created with the names below will be executed at the
+specified times:
+
+    subroutine name    properties
+    ---------------    ----------
+    owl::startup()     run when owl first starts
+    owl::shutdown()    run when owl exits
+    owl::format_msg()  run when a new message arrives, the return
+                          value is used to display the message on the
+                          screen
+    owl::receive_msg() run when a message is received, and after
+		       it has been added to the message list
+
+
+The following variables will be set each time a message is recevied:
+
+    $owl::class, $owl::instance, $owl::recipient,
+    $owl::sender, $owl::opcode, $owl::zsig,
+    $owl::msg, $owl::time, $owl::host, @owl::fields, $owl::id
+
+The "appendtosepbar" variable may be set in owl::format_msg()
+to set text to be appended to sepbar that separates the received
+message list from the edit window.
Index: doc/intro.txt
===================================================================
--- doc/intro.txt	(revision 3969e3abe1e0ff0577ae1054124f90af20e8e3c1)
+++ doc/intro.txt	(revision 675ce49ec986337de5dffba27f20b2a1e23fb442)
@@ -8,7 +8,7 @@
 
 Owl is a tty, curses-based instant messaging client.  This is a quick
-guide to learning how to use it.  Currently it supports only zephyr,
-but other messaging protocols, including AIM and Jabber, are on the
-way.  Some major features of owl include:
+guide to learning how to use it.  Currently Owl supports AIM & zephyr,
+but other messaging protocols, including Jabber, are on the way.  Some
+major features of owl include:
 
    o) As a tty client it can be run over telnet, rlogin or text ssh
@@ -28,26 +28,28 @@
 ==========================
 
-Owl will run happily without a configfile, so to get started just run
-the program.  Owl will take over the terminal window it is started in,
-so you may wish to have another terminal window available at the same
-time.
+Owl will run happily without a configuration file, so to get started
+just run the program.  Owl will take over the terminal window it is
+started in, so you may wish to have another terminal window available
+at the same time.
 
 On Athena you can find owl in the ktools locker.  To run it, type:
 
-        add ktools
-        owl
+     add ktools
+     owl
 
 at the Athena% prompt.  If you wish to run the latest beta release of
 owl use:
 
-        add ktools
-        owl-beta
-
-instead.
+     add ktools
+     owl-beta
+
+instead.  The beta release will often have newer features, but is not
+as tried and true as the production release.  As a result it may be
+less stable.
 
 The Screen Layout
 -----------------
 There are three main parts to the owl screen.  The large top portion
-of the screen is where zephyrs are displayed.  The status bar
+of the screen is where messages are displayed.  The status bar
 separates this area from the one below and displays owl status
 information.  The space below that is used to type messages and is
@@ -72,4 +74,21 @@
 arguments to the zwrite command as you normally would.
 
+Sending an AIM message
+----------------------
+
+Before sending an AIM message you must login to AOL Instant Messenger.
+Use the 'aimlogin' command, with your screenname as an argument:
+
+     aimlogin <screenname>
+
+You will be prompted for your password, which you must enter.  Once
+you are successfully logged in you can send an AIM message by pressing
+the 'a' key, which will bring up an 'aimwrite' command:
+
+     aimwrite <screenname>
+
+Supply the screen name you wish to write to as an argument and then
+send the message just as you would send a zephyr, as described above.
+
 Manipulating Messages
 ---------------------
@@ -79,47 +98,47 @@
 messages:
 
-	n		move to the next non-deleted message
-	p		move to the previous non-deleted message
-	C-n , down	move to the next message
-	C-p , up	move to the previous message
-	<		move to the first message
-	>		move to the last message
-	C-v		page down
-	M-v		page up
-	right		scroll the screen to the right
-	left		scroll the screen to the left
-	P		move to the next personal message
-	M-P		move to the previous personal message
+     n		  move to the next non-deleted message
+     p		  move to the previous non-deleted message
+     C-n or down  move to the next message
+     C-p or up	  move to the previous message
+     <		  move to the first message
+     >		  move to the last message
+     C-v          page down
+     M-v          page up
+     right        scroll the screen to the right
+     left         scroll the screen to the left
+     P            move to the next personal message
+     M-P          move to the previous personal message
 
 When you are ready to delete a message you can mark it for deletion
-and a 'D' will appear to the left of the message.  Messages will not
-actually be removed until you perform an expunge.  The following keys
-are used to delete, undelete and expunge messages:
-
-	d		mark a message for deletion
-	u		unmark a message for deletion
-	x		expunge deleted messages
-	T		mark all 'trash' messages for deletion
-        M-D		mark all messages in the view for deletion
-	M-u		unmark all messages in the view for deletion
-
-If you would like to respond to a zephyr sent to you there is a reply
+with the 'd' key, and a 'D' will appear to the left of the message.
+Messages will not actually be removed until you perform an expunge.
+The following keys are used to delete, undelete and expunge messages:
+
+     d		  mark a message for deletion
+     u		  unmark a message for deletion
+     x		  expunge deleted messages
+     T		  mark all 'trash' messages for deletion
+     M-D          mark all messages in the view for deletion
+     M-u          unmark all messages in the view for deletion
+
+If you would like to respond to a message sent to you there is a reply
 shortcut:
 
-	r               Reply.  Personal zephyrs get a personal reply,
-                        class/instance zephyrs get a public reply.
-	R		Reply to sender.  Always replies personally
-                        to the user.
-        M-r             Reply but allow editing of the command line.
-        M-R             Reply to sender but allow editing of the
-                        command line.
+     r            Reply.  Personal messages get a personal reply,
+                       group messages get a group reply.
+     R            Reply to sender.  Always replies personally
+                       to the sender.
+     M-r          Reply but allow editing of the command line.
+     M-R          Reply to sender but allow editing of the
+                       command line.
 
 In the event that the current message is too large to fit on the
 screen, you can scroll within the message using the following keys:
 
-	SPACE		page down
-	b		page up
-	RETURN		line down
-	BACKSPACE	line up
+     SPACE        page down
+     b            page up
+     RETURN       line down
+     BACKSPACE    line up
 
 The message pointer will change to indicate that the message is not
@@ -128,6 +147,6 @@
 Two other keys that relate to the current message:
 
-	i 		print detailed information about the message
-	w 		instruct netscape to visit a URL in the message
+     i 		  print detailed information about the message
+     w            instruct netscape to visit a URL in the message
 
 Other Functions
@@ -135,14 +154,14 @@
 Some other functions that can be performed with a single keystroke:
 
-	A		toggle zaway on or off
-	C-l		refresh and resize the screen
-	C-z		suspend
+     A            toggle zephyr zaway on or off
+     C-l          refresh and resize the screen
+     C-z          suspend
 
 Command Mode
 ------------
 Owl has a command mode from which you can enter more detailed commands
-for owl to process.  To enter command mode press the colon (':') key:
-
-	:		begin command mode
+for Owl to process.  To enter command mode press the colon (':') key:
+
+     :		  begin command mode
 
 Owl will give you a command prompt and you can begin typing your
@@ -152,10 +171,10 @@
 you can use the command:
 
-        show commands
+     show commands
 
 And for detailed information on the syntax and use of a command you
 can use:
 
-        help <command>
+     help <command>
 
 For example "help zwrite" will display all the options available when
@@ -169,51 +188,50 @@
 variable.  For example:
 
-        set personalbell on 
-
-will set the value of the variable 'personalbell' to on.  The command:
-
-	print personalbell
+     set personalbell on 
+
+will set the value of the variable 'personalbell' to 'on'.  The
+command:
+
+     print personalbell
 
 will show you the current value.  The 'print' command with no
 arguments:
 
-        print
+     print
 
 Owl will show you the value of all variables.  You can also use
 
-        show variables
-        show variable <variable>
+     show variables
+
+     show variable <variable>
 
 To display further information on owl variables.
 
-Views
------
+
+================
+Section 3: VIEWS
+================
+
 Owl always displays a current "view" of messages.  The view describes
 which set of messages should be included on the display.  The default
 view is called "all" and includes every message.  However, you can
-narrow the view to a particular set of zephyrs:
-
-	M-n		Narrow view to the selected conversation
-	M-N		Narrow view to selected conversation by instance
-	V		Return to the home view (the 'all' view)
-	X		Expunge messages and return to home view
-
-If you press M-n while the pointer is on a personal zephyr, the view
+narrow the view to a particular set of messages:
+
+     M-n          Narrow view to the selected conversation
+     M-N          Narrow view to selected conversation by instance
+     V            Return to the home view (the 'all' view)
+     X            Expunge messages and return to home view
+
+If you press M-n while the pointer is on a personal message, the view
 will be narrowed to the conversation with that user only.  If used on
-a class zephyr the conversation will be narrowed to that class, with
-a few special exceptions like class MESSAGE.
-
-There are also some owl commands related to views:
-
-        viewclass <class>     Narrow the view to the named class
-        viewuser <user>       Narrow the view to the named user
+a group message the conversation will be narrowed to that group.
+
+There are also some Owl commands related to views:
+
+     viewclass <class>     Narrow the view to the named zephyr class
+     viewuser <user>       Narrow the view to the named user
 
 More information on views and how they work is included in the section
 on "FILTERS AND COLORS".
-
-==========================================
-Section 3: KEYBINDINGS AND COMMAND ALIASES
-==========================================
-
 
 =============================
@@ -221,8 +239,91 @@
 =============================
 
-
+Filters
+-------
+Owl will allow you to create custom message filters.  A message filter
+is an expression that matches a set of messages based on certain
+criteria.  Owl comes with a number of build-in filters already.  You can
+view a list of them with the command:
+
+     show filters
+
+The default filters include:
+
+     all              Matches all messages
+     none             Matches no messages
+     personal         Only personal messages (no group messages)
+     login            Login/Logout notifications
+     auto             Messages generated by automated programs
+     out              Messages sent from you to another user
+     aim              AIM messages
+     zephyr           Zephyr messages
+     trash            "Trash" messages
+     ping             Zephyr pings
+     reply-lockout    Messages for which the reply commands
+                          should not work
+
+If you wish to view the messages that match a particular filter, use
+the 'view' command.  For example:
+
+     view personal
+
+This will display only personal messages on the screen.  You can
+change back to the 'all' view by pressing the 'V' key (capitalized).
+Note that the 'v' key (not capitalized) is a shortcut to bring up the
+'view' command.
+
+You can also create your own filters.  For more information on this,
+consult the Owl Advanced Users Guide.
+
+Colors
+------
+Every filter can have a color associated with it.  Messages matching
+the filter will then be displayed in that color if your terminal
+supports it.  The color for a filter can be set by using the '-c'
+option to the filter command.  For example:
+
+     filter personal -c white
+
+This cause all messages in the 'personal' filter to be displayed in
+white.  You can produce a list of the colors available to Owl with the
+command:
+
+     show colors
+
+If a message matches more than one filter it will be displayed in the
+color specified in the last filter listed in the 'show filters'
+command.
+
+If you would like your color settings to persist, such that they are
+preset every time you start Owl, please read the "Saving Your
+Settings" section below.
+
+===============================
+Section 5: SAVING YOUR SETTINGS
+===============================
+
+Any changes you make to Owl are lost when the program is terminated,
+unless you specify otherwise.  If you would like a setting to persist
+such that it is available every time you start Owl you can use the
+word 'startup' before any command.  For example:
+
+     startup filter personal -c white
+
+Will instruct Owl to color personal messages white both in the current
+session and in any future Owl session.  You may revert this behavior
+with the 'unstartup' command:
+
+     unstartup filter personal -c white
+
+which will not affect the current session, but will cause future
+sessions not to take this action.
+
+Here is another example, this instructs Owl to display zephyr ping
+messages:
+
+     startup set rxping on
 
 ==========================
-Section 5: THE CONFIG FILE
+Section 6: THE CONFIG FILE
 ==========================
 
@@ -263,4 +364,9 @@
 
 
+==========================================
+Section 4: KEYBINDINGS AND COMMAND ALIASES
+==========================================
+
+
 ==============================
 Section 6: FURTHER INFORMATION
