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
+===================
