Index: doc/code.txt
===================================================================
--- doc/code.txt	(revision 7d4fbcdd0df83802711454fdafce2c9d592bf431)
+++ doc/code.txt	(revision 7d4fbcdd0df83802711454fdafce2c9d592bf431)
@@ -0,0 +1,196 @@
+
+TYPES / CLASSES / SOURCE FILES
+------------------------------
+
+cmd:	     Underlying implementation of command table management
+	     and command dispatching.  Also handles the implementation
+	     of command aliases.
+
+commands:    Dispatching for commands and handling of their arguments.
+	     (Commands are the interface exported to the user.)
+	     Many commands tend to be backed by functions.
+	     In general, a command takes a string as an argument
+	     and optionally returns a string.
+	     At the top of the file is a table mapping
+	     command names and help to functions implementing them.
+	     The standard entrypoint for executing a command
+	     is owl_function_command("foo");
+	     Commands are only active within specific contexts,
+	     and attempts to call them from invalid contexts will fail.	     
+
+context:     A context specifies the current state of owl, in terms 
+	     of which modal window is active and which point
+	     in its life owl is in (eg, in startup, or running).
+	     This is implemented as a bitmask and there is 
+	     some hierarchy.  Commands may restrict themselves
+	     to only running in a limited number of contexts
+	     to prevent commands from being executed at points
+	     when they not make sense.  Also, the data from
+	     the active context (eg, a pointer to an active window)
+	     may be passed to a command.
+
+dict:	     Simple dictionary abstraction mapping from strings to pointers.
+
+editwin:     Text editing window (both multiline and single line).
+	     Sometimes also referred to as typewin.
+
+filter:	     Patterns which match messages.  These may 
+	     contain multiple filterelements which may be 
+	     combined together (eg, by "and" and "or").
+	     
+filterelement: An element of a filter which matches on some 
+	       attribute of a message.
+
+fmtext:      Formatted text routines (handles things like @i{foo}).
+	     These are particularly useful for building up
+	     text regions that are to be rendered on-screen,
+	     as they resize memory as needed, and they have 
+	     routines for cropping as needed.
+
+functions:   Where most features are implemented.
+	     Users should always interact with functions through commands.
+	     In general, functions are abstract entrypoints into the
+	     system and attempt to hide access to global state.
+
+global:	     Global state and variables and toplevel objects.
+	     owl.h defines "g" as a singleton instance of owl_global.
+	     Where possible/appropriate, most accesses to global data should
+	     be from a limited number of files (eg, from owl.c and 
+	     functions.c).  Consider whether you really need to before
+	     adding in uses of global.
+
+help:	     Help strings for commands and key bindings.
+	     Most of this is now in keys.c, commands.c, and variables.c,
+	     along with the definition of commands and keybindings.
+
+keys:	     Default key binding definitions for all keymaps.
+	     This also includes default actions for keymaps.
+
+keybinding:  Binding between a sequence of keypresses and a command.
+	     When executed, this executes the commands.  The sequence
+	     of keypresses is kept as a stack.  Keybindings are a part
+	     of keymaps.
+
+keypress:    Utility routines for translating between keypress values and
+	     and human-readable key names.
+
+keymap:      Contains both keymap and keyhandler.  A keymap is contains a
+	     list of keybindings, a sub-keymap, and optionally a
+	     default handler function.  The sub-keymap is a more
+	     general keymap which is consulted if the specific keymap
+	     doesn't contain a match.  (For example, the "global"
+	     keymap is the ancestor of all other keymaps.)  The
+	     keyhandler is a collection of keymaps which handles
+	     checking for key matches within keymaps.  It maintains a
+	     stack of keypresses and compares them against the
+	     bindings in keymaps.  It also handles ESC as a prefix for
+	     Meta.  At any one time, there is exactly one active
+	     keymap which determines where keybindings are looked for
+	     (along with its submaps).
+
+list:	     Simple list abstraction.  (Uses realloc to resize the list.)
+
+logging:     Interface to incoming / outgoing zephyr logging.
+
+mainwin:     Window that displays the list of messages.
+	     (Sometimes also referred to as recwin.)
+
+message:     Abstraction to messages.  Currently, messages
+	     are either of type zephyr or of type admin.
+
+messagelist: List of messages.
+
+owl.c:	     main() and signal handlers and other initial setup.
+	     Also contains the main loop, which is roughly:
+	     - handle scheduled resizes, and anything that might result
+	     - while zephyrs are pending, grab incoming zephyrs 
+	       and handle them (which includes formatting them
+	       with either perl extension or default formatter
+	       as part of owl_message_create_from_zephyr).
+	     - updates mainwin display if there are new zephyrs
+	     - displays and updates popwins and the terminal as necessary
+	     - sends characters to the popwin, recwin/mainwin, 
+	       or typewin/editwin
+
+
+owl.h:	     Prototypes for all types, as well as global constants.
+
+owl_prototypes.h:  Autogenerated prototypes for all functions.
+		   Created by codelist.pl.
+
+popwin:      Modal pop-up window container. 
+	     Usually contains a viewwin for read-only scrolling text.
+
+readconfig:  Perl extension interface.
+
+text:	     Text formatting utilities (ie, indenting, truncating, etc)
+
+util:	     Misc utility functions that don't fit anywhere yet:
+	     - sepbar rendering 
+	     - tokenizing and parsing utilities
+	     - downstr
+	     - stristr
+	     - owl_malloc/free/realloc
+
+variable:    Interface to setting and getting variables.
+	     Current variable types include bool, int, string, and other.
+	     There's also an enum type which is variant of int.
+	     Variables can be created and customized here as well.
+
+varstubs.c:  Autogenerated headers for accessing global variables
+
+view:	     A collection of messages determined by a filter.
+	     Many operations may be performed on the members
+	     of a view, and a view can be narrowed-to for display.
+
+viewwin:     Read-only scrolling text displayed in a modal popwin.
+	     This is also sometimes called "popless".
+
+zephyr:	     Routines for interfacing to zephyr.
+
+zwrite:	     Outgoing zephyrs.  Sends pings on creation,
+	     handles command arguments, etc.
+
+
+===========================================================================
+
+CURSES WINDOWS
+--------------
+
+The four curses windows on the screen are
+
+  recwin - receiving window
+  sepwin - seperator window
+  msgwin - message window
+  typwin - typing window
+
+
+===========================================================================
+
+
+MISC THINGS
+-----------
+
+userclue:  right now userclue is just used to decide if you sub to
+	   classes other than the default.  If you don't it doesn't bother
+	   making your personal messages bold since there's no point in
+	   making every message bold.
+
+
+
+===========================================================================
+
+Conventions and Design Criteria
+-------------------------------
+
+	There are no hard rules for memory allocation.  In general I
+	have the caller allocate memory for objects themselves and any
+	memory the object creates gets freed with object_free().
+	Functions should document if the caller needs to free
+	something, and this should be the exception to the rule.
+
+	Owl should be generally useful out-of-the-box without 
+	extensive configuration, for most people's needs.  
+	People shouldn't have to spend days tweaking
+	with config files before being happy switching to it.
+
Index: doc/contributors
===================================================================
--- doc/contributors	(revision 7d4fbcdd0df83802711454fdafce2c9d592bf431)
+++ doc/contributors	(revision 7d4fbcdd0df83802711454fdafce2c9d592bf431)
@@ -0,0 +1,41 @@
+Owl was primarly written by James Kretchmar at the Massachusetts
+Institute of Technogloy.  The following people have also made major
+contributions.
+
+Erik Nygren
+   Complete overhaul of the variable system
+   perl, aperl and pperl commands
+   Multiple browser support
+   Support for older versions of lib zephyr
+   Many bug fixes and features
+   Code documentation
+   Example config files
+
+Stephen Gildea
+   Extensive testing and feedback
+
+Mark Eichin
+   Bug fixes
+   Debian packaging
+
+Greg Hudson
+   Hack to work around waiting for HMACKs
+
+David Resnick
+   Build fixes and cleanup
+ 
+Marc Horowitz
+   Embedded perl advice
+
+Jeremy Daniel
+   Bug fixes and patches
+   First version of color support
+
+Andy Ellis, Erin Panttaja, Gisele Proulx
+Ron Hoffmann, Jag Patel, Tara Holm
+Heather Wakefield, Emiliy Havens,
+Matt Braun, Jeff Schiller
+   Beta testing
+
+Anne LaVin
+   ASCII Art Owl
Index: doc/intro.txt
===================================================================
--- doc/intro.txt	(revision 7d4fbcdd0df83802711454fdafce2c9d592bf431)
+++ doc/intro.txt	(revision 7d4fbcdd0df83802711454fdafce2c9d592bf431)
@@ -0,0 +1,227 @@
+Owl is a tty, curses-based zephyr client.  This is a quick guide to
+learning how to use it.
+
+====================
+OVERVIEW OF FEATURES
+====================
+o) As a tty client it can be run over telnet, rlogin or text ssh sessions
+
+o) It uses a perl configuration file for setting preferences and
+   formatting messages
+
+o) emacs style editing of messages
+
+o) It is easy to use and runs without a configfile.
+
+o) There will future support for AIM and ICQ
+
+o) There will be future support for advanced sorting of messages
+
+===============
+GETTING STARTED
+===============
+Owl will run happily without a configfile, so to get started just run
+it.  Owl will take over the terminal window it's started in.
+
+The Screen
+----------
+There are three main parts to the screen.  The large top portion of
+the screen is where zephyrs are displayed.  The status bar separates
+this area from the one below and displays some status information.
+The space below that is used to type in messages and is also used by
+owl to give warnings and information to the user.
+
+Sending a Zephyr
+----------------
+To send a zephyr to yourself hit the 'z' key.  This will start a
+zwrite command, which you can finish by typing the name of the user
+you wish to send to, followed by enter.  Begin typing your message.
+You will notice that most emacs-style editing is available.  When you
+are ready to send type Control-D.  If you wish to cancel type
+Control-C.
+
+If instead of a user you wish to send to class/instance simply supply
+-c and -i arguments to the zwrite command.
+
+Manipulating Messages
+---------------------
+When there are one or more zephyrs in the message window, one of them
+will be the 'current' message.  Owl will indicate which one it is with
+an arrow to the left of the message.  The following keys will move you
+between 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
+	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
+	T		Mark all 'trash' messages for deletion
+
+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.
+
+	d		mark a message for deletion
+	u		unmark a message for deletion
+	x		expunge deleted messages
+	T		mark all automated messages for deletion
+
+If you would like to respond to a zephyr sent to you there is a reply
+shortcut.  This will reply to a personal zephyr, or if the zephyr is
+sent to a zephyr class it will reply to the zephyr class.
+
+	r		reply to a zephyr
+
+You can scroll within the current message using:
+
+	SPACE		page down
+	b		page up
+	RETURN		line down
+	BACKSPACE	line up
+
+The pointer will change to indicate that the message is not starting
+at the first line.
+
+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
+
+
+Other Functions
+----------------
+Some other funcions that can be performed with a single keystroke:
+
+	A		toggle zaway
+	h		print the help screen
+	C-l		refresh and resize the screen
+	C-z		suspend
+
+Command Mode
+------------
+Owl has a command mode where you can enter more detailed commands for
+owl to process.  To enter command mode:
+
+	:		begin command mode
+
+Owl will give you a command prompt and you can begin typing your
+command.  Type Enter to execute the command, Control-C to cancel.
+Currently support commands are:
+
+	quit , exit	exit owl
+	zwrite		send a zephyr
+	reply		reply to the current zephyr
+	set		set a variable
+	print		print a variable
+	zlog [in|out]	send a login or logout message
+	version		print the owl version number
+	subscribe	subscribe to a class, instance, recipient
+	unsubscribe	unsubscribe from a class, instance, recipient
+	unsuball	unsubscribe from all messagse
+	getsubs		print a list of current subscriptions
+	zlocate		locate a user
+	info		print detailed information about a message
+	help		print the help screen
+	next		move to the next message
+	prev		move to the previous message
+	next-notdel	move to the next non-deleted message
+	prev-notdel	move to the previous not-deleted message
+	expunge		expunge messages marked for deletion
+	first		move to the first message
+	last		move to the last message
+	resize		resize owl to the current window
+	suspend		suspend owl
+	exec		run a shell command
+	zaway [on|off|<msg>]  Turn zaway on, off, or set the message
+	load-subs	load subscriptions from a file
+	status		print info about owl status
+	about		print info about owl
+
+Variables
+---------
+The 'set' and 'print' commands let set and print the values of owl
+variables.  The currently supported variables are these:
+
+Variables:                                                                                        
+     name            settings  default      meaning                                                  
+     --------------- --------  -------      -------                                                  
+     appendtosepbar  <string>            string to append to the end of the sepbar                
+     bell            on,off    on        enable / disable the terminal bell                       
+     burningears     on,off    off       [NOT YET IMPLEMENTED] beep on messages matching patterns 
+     classlogging    on,off    off       turn class logging on or off                             
+     classpath       <path>    ~/zlog/class
+				         path for logging class zephyrs                           
+     debug           on,off    on        whether debugging is enabled                             
+     debug_file      <path>    /var/tmp/owldebug
+					 path for logging debug messages when debugging is enabled
+     disable-ctrl-d  on,off    off       don't send zephyrs on C-d                                
+												  
+     displayoutgoing on,off    on        display outgoing messages                                
+     logging         on,off    off       turn personal logging on or off                          
+     loginsubs       on,off    on        load logins from .anyone on startup                      
+     logpath         <path>    ~/zlog/people
+					 path for logging personal zephyrs                        
+     personalbell    on,off    off       ring the terminal bell when personal messages are receive
+     rxping          on,off    off       display received pings                                   
+     shutdownlogout  on,off    on        send a logout message when owl exits                     
+     startuplogin    on,off    on        send a login message when owl starts                     
+     summarymode     on,off    off       [NOT YET IMPLEMENTED]                                    
+     txping          on,off    on        send pings                                               
+     typewinsize     int > 0   8         number of lines in the typing window                     
+     webbrowser  none,netscape,galeon netscape web browser to use to launch URLs             
+     zaway_msg         <string>  "I'm sorry..."
+					   current zaway msg for responding to zephyrs when away    
+     zaway_msg_default <string>  "I'm sorry..."
+				           default zaway msg for responding to zephyrs when away  
+     zsig              <string>            zephyr signature                                         
+     zsigproc          <path>    <null>    name of a program to run that will generate zsigs        
+
+
+================
+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.
+
+
+===================
+FURTHER INFORMATION
+===================
Index: doc/owl.1
===================================================================
--- doc/owl.1	(revision 7d4fbcdd0df83802711454fdafce2c9d592bf431)
+++ doc/owl.1	(revision 7d4fbcdd0df83802711454fdafce2c9d592bf431)
@@ -0,0 +1,59 @@
+.TH owl 1 "21 May 2002"
+.SH NAME
+owl \- tty based zephyr client
+.SH SYNOPSIS
+.B owl
+[ \-n
+]
+[ \-c
+.I configfile
+]
+[ \-t
+.I tty
+]
+[ \-v
+]
+
+.br
+.SH DESCRIPTION
+.B Owl
+is a fully integrated tty based zephyr client for sending and
+receiving zephyrs.  It is curses-based, allows for emacs style editing
+of outgoing messages and uses a perl configuration language for
+setting options and customizing message formatting.  Owl will also run
+happily without a configuration file.
+
+Once owl is started typing 'h' will display a help screen.  Typing ':'
+enters command mode, allowing the user to type an owl command line.
+
+.PP
+.SH USE
+The following command line options are avilable when running owl:
+
+.B \-n
+.IP
+Do not subscribe to messages on startup.  By default owl subscribes to
+the default subscriptions and to anything found in ~/.zephyr.subs
+.LP
+
+.B \-c \fIconfigfile\fP
+.IP
+Specifiy an alternate config file for owl to use.  By default it looks
+for ~/.owlconf
+.LP
+
+.B \-t \fItty\fP
+.IP
+Specifiy the tty name to use for the zephyr location.
+.LP
+
+.B \-v
+.IP
+Print the version number of owl and exit.
+.LP
+
+.SH AUTHOR
+Written by James Kretchmar at the Massachusetts Institute of
+Technology.
+Comments, questions, and bug reports may be mailed to
+\fBbug-ktools@mit.edu\fP.
