Index: ChangeLog
===================================================================
--- ChangeLog	(revision 282ec9b75cee20fb97aa588cedb3440feb68b563)
+++ ChangeLog	(revision c82b055f7e68fdc0972d575b4222a19fff792159)
@@ -4,5 +4,6 @@
         Make sure that a newline is always at the end of messages
 	        returned by perl style formatting functions.
-	Add owl::login to legacy variables populated for format_msg.
+	Add owl::login and owl::auth to legacy variables populated for format_msg.
+	Additions to intro.txt and advanced.txt documents.  (Still in progress.)
 
 2.0.8-pre-2
Index: doc/advanced.txt
===================================================================
--- doc/advanced.txt	(revision 675ce49ec986337de5dffba27f20b2a1e23fb442)
+++ doc/advanced.txt	(revision c82b055f7e68fdc0972d575b4222a19fff792159)
@@ -5,11 +5,8 @@
 
 =========================
-Section X: CUSTOM FILTERS
-=========================
-
-
-==========================
-Section X: THE CONFIG FILE
-==========================
+Section X: COMMAND ALISES
+=========================
+
+[see Section 4 in intro.txt, which may want to be moved here]
 
 =======================
@@ -17,17 +14,9 @@
 =======================
 
-
-=========================
-Section X: COMMAND ALISES
-=========================
-
-
-=================
-Section X: STYLES
-=================
-
-
-- - - - - - - - - - - - - - - - - - - - - - - - - - -
-
+[see Section 4 in intro.txt, which may want to be moved here]
+
+=========================
+Section X: CUSTOM FILTERS
+=========================
 
 For example, the following
@@ -69,18 +58,12 @@
 
 
-==========================
-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.
+=========================================
+Section 6: THE PERL EXTENSION CONFIG FILE
+=========================================
+
+*** WARNING: This interface is still evolving and may change over time ***
+
+The ~/.owlconf file is interpreted by the perl interpreter. 
+You may specify an alternate file by running owl with "owl -c <configfile>".
 
 Subroutines created with the names below will be executed at the
@@ -91,18 +74,128 @@
     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::format_msg()  run to format messages when using the perl style.
+		       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.
+It is possible to call back into owl and execute owl commands
+from within these functions.  This is particularly useful
+in owl::startup for setting up your initial owl environment.
+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 to 
+the value "/mit/kretch/bin/getzsig foo".
+Note that you will need to watch out for perl quoting issues.
+[It may be worth talking about them a little here...]
+
+Both owl::format_msg and owl::receive_msg are passed perl owl::Message
+objects which have methods for accessing the attributes of the message.  
+
+(Caveat: Note that these owl::Message objects are currently only
+	 snapshots of the message contents that are created as needed.  As
+	 such, there could be multiple owl::Message objects for the same owl
+	 message.  Use the msgid if you want to uniquely identify individual
+	 messages.)
+
+All owl::Message objects contain the following methods:
+
+    type      - returns the type of the message ("zephyr", "aim", "admin")
+    direction - returns "in" or "out" for incoming or outgoing messages
+    time      - returns a string of the time when the message showed up
+    id	      - returns a unique id for the message
+    body      - returns the body text of the message
+    sender    - returns the sender of the message
+    recipient - returns the recipient of the message
+    login     - returns either "login", "logout", or "none"
+    is_login  - returns true if this is a login message
+    is_logout - returns true if this is a logout message
+    is_loginout - returns true if this is a login or logout message
+    is_incoming - returns true if this is an incoming message
+    is_outgoing - returns true if this is an outgoing message
+    is_deleted  - returns true if this message is marked for deletion
+    is_<type>	- returns true if the message is of type <type> (eg, is_zephyr)
+    delete	- marks the message for deletion
+    undelete	- unmarks the message from deletion
+    pretty_sender - returns a cleaned up version of the sender
+
+The following owl::Message methods are only applicable to
+various message types:
+
+    header	- returns the admin message header line  (admin)
+    is_personal - returns true if this is a personal message (aim,zephyr)
+    is_private  - returns true if this was a private message (zephyr)
+    login_tty	- returns the login tty for login messages (zephyr)
+    login_host  - returns the login host for login messages (zephyr)
+    zwriteline  - returns the zwrite command line for outgoing zephyrs (zephyr)
+    zsig	- returns the zsig (zephyr)
+    is_ping	- returns true if this was a zephyr ping (zephyr)
+    is_mail	- returns true if this was a new mail notification (zephyr)
+    class	- returns the zephyr class (zephyr)
+    instance	- returns the zephyr instance (zephyr)
+    realm	- returns the zephyr realm (zephyr)
+    opcode	- returns the zephyr opcode (zephyr)
+    hostname	- returns the zephyr sender's hostname (zephyr)
+    fields	- returns the zephyr fields as a perl list (zephyr)
+    auth	- returns whether this zephyr was authentic (zephyr)
+
+An example formatting function that formats messages so that they only
+list the direction, sender, and time would be:
+
+    sub owl::format_msg {
+	my ($m) = @_;    # assigns the message object passed
+			 # to this function to $m
+	return sprintf "[direction=%s] from sender %s at %s\n",
+		       $m->direction,
+		       $m->sender,
+		       $m->time;
+    }
+
+In the above, $m is the owl::Message object and 
+its methods are called with $m->METHODNAME.
+
+An example receiver function that tags all zephyr pings for 
+deletion would be:
+
+    sub owl::receive_msg {
+	my ($m) = @_;    # assigns the message object passed
+			 # to this function to $m
+	if ($m->is_zephyr and $m->is_ping) {
+	   $m->delete();
+	}
+    }
+
+
+=================
+Section X: STYLES
+=================
+
+
+
+
+
+========================================
+Section 7: PERL COMMANDS FROM WITHIN OWL
+========================================
+
+Perl code may be executed from within owl with:
+
+  perl <perlcode>
+
+If you use pperl instead of perl, the return value
+of the perl command will be displayed in a pop-up window.
+This is particularly useful within key bindings 
+and aliases.  For example:
+
+  alias finger pperl $x=owl::getcurmsg()->hostname; `finger \@$x`;
+
+Will cause the "finger" command to be used to finger at the host
+where the current message came from.  You can then bind this 
+to the "f" key with:
+
+   bindkey recv f command finger
+
+See the section above for detailss of commands and functions
+that are available from within the perl interpreter.
Index: doc/intro.txt
===================================================================
--- doc/intro.txt	(revision 675ce49ec986337de5dffba27f20b2a1e23fb442)
+++ doc/intro.txt	(revision c82b055f7e68fdc0972d575b4222a19fff792159)
@@ -336,6 +336,5 @@
      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.
+will set the owl variable zsigproc.  
 
 Subroutines created with the names below will be executed at the
@@ -346,16 +345,14 @@
     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::format_msg()  run to format messages when using the perl style.
+		       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
+Both owl::format_msg and owl::receive_msg are passed
+perl owl::Message objects which contain attributes of the message.
+Please see the advanced.txt file for further documentation
+of the Perl extension API.
 
 The "appendtosepbar" variable may be set in owl::format_msg()
@@ -368,4 +365,95 @@
 ==========================================
 
+Aliases
+-------
+
+Command aliases allow users to create shortcuts
+for commonly used commands.  Aliases can be created wit
+the alias command:
+
+    alias NAME VALUE
+
+For example:
+
+    alias zw zwrite
+
+Will make "zw" an alias for the zwrite command.  As such, "zw aphacker"
+will be expanded to "zwrite aphacker".  If the value of an
+alias is multiple words, use of the alias will result in the alias
+command name being replaced by the sequence of words.
+Any arguments following the alias name will be appended
+after the expanded alias value.  For example:
+
+   alias vs view -s
+
+will result in "vs standard" being expanded to "view -s standard".
+There is not yet any way to allow an alias to take arguments
+that will be inserted in the middle of the expansion.
+
+
+Separating Commands
+-------------------
+
+Multiple commands can be grouped together with parentheses
+and then separated by semicolons.  For example:
+
+   ( smartnarrow ; delete view ; expunge ; view all )
+
+Will result in the four commands being executed
+in sequence.  This is particularly useful with key bindings
+and coommands.  For example:
+
+   alias sn-delete ( smartnarrow ; delete view )
+
+will create an "sn-delete" alias that will smartnarrow
+to a view and them mark the view for deletion.
+
+Using "show commands" will list all existing aliases.
+
+
+Key Bindings
+------------
+
+New key bindings may be created with the "bindkey" command.  Each key
+binding is associated with a particular keymap which is applicable in
+a particular context/situation.  When the key associated with a
+binding is pressed in the right context, it will result in an owl
+command being run.  The syntax is:
+
+   bindkey <keymap> <keyseq> command <command>
+
+For example:
+
+   bindkey recv C-k command delete 
+
+will bind Control-k to the delete command, but only in the 
+recv window context.
+
+Some keymaps inherit their bindings from more 
+general keymaps.  The valid keymaps are:
+
+  - global	      - owl-wide defaults (apply everywhere)
+    |-edit	      - all text editing and command windows
+    |  |-editmulti    - multi-line text editing windows
+    |  |-editline     - single-line editing and command windows
+    |  |-editresponse - single-line responses to questions
+    |-popless	      - scrolling pop-up windows
+    |-recv	      - the main message list window 
+			where received messages are displayed
+
+The existing key bindings can be shown with "show keymaps".
+The use of "show commands" will list all available commands.
+Note that not all commands may be used in all contexts.
+
+Key sequences may be surrounded by quotes and include 
+a sequence of keys that must be pressed in order
+to execute the command.  For example:
+
+   bindkey recv "C-s v" command view -s vt
+
+will result in "Control-s" followed by "v" in the recv window
+causing the command "view -s vt" to be run.
+
+
 
 ==============================
