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