doc updates

--HG--
branch : pmacs2

MODES

@@ -3,11 +3,10 @@ modes work, how you might create one yourself, etc.
 
 1. What are modes?
 
-Pmacs uses modes to determine what actions can be applied to a buffer, which
+Pmacs uses modes to determine what which keys should apply which actions, how
-keys should apply which actions, how the buffer should be highlighted, how the
+the buffer should be highlighted, how the buffer should be indented, and any
-buffer should be indented, and any other per-buffer configuration. The default
+other per-buffer configuration. The default mode ("Fundamental") provides the
-mode ("Fundamental") provides the base functionality which all other modes
+base functionality which all other modes inherit.
-inherit.
 
 2. Where do they come from?
 
@@ -27,8 +26,8 @@ The one thing every mode has in common is that they map key bindings to actions
 to be taken. They do this via self.bindings, a dictionary mapping action names
 (i.e. 'page-down') to a tuple of key bindings (i.e. ('C-v', 'PG_DN',)).
 
-Modes subclass mode2.Fundamental, and they call mode2.Fundamental.__init__ to
+Modes subclass mode.Fundamental, and they call mode.Fundamental.__init__ to run
-run the standard mode initialization (including building the default bindings
+the standard mode initialization (including building the default bindings
 dictionary); they can later modify or overwrite this dictionary if they choose.
 
 There are at least 3 optional behaviors modes can make use of:
@@ -46,11 +45,17 @@ documents.
 Syntax highlighting uses a hybrid lexing/parsing process to break each line of
 the buffer down into one or more lexical tokens; these tokens are primarily
 used to highlight parts of the buffer different colors. The colors to use are
-defined by self.colors, a dictionary mapping token-names to a tuple consisting
+defined by application.colors, a dictionary mapping token-names to a tuple
-of at least a foreground color and a background color.
+consisting of at least a foreground color and a background color. Modes can
+define a self.colors dictionary which will be added to the application; however,
+modes are not permitted to override the global defaults in this way (the user
+can override them via ~/.pmc/conf in whatever way is desired).
+
+Modes are encouraged to use "generic" token names when appropriate; modes can
+also "namespace" their tokens to allow for mode-specific customization.
 
 Explaining how to write a Grammar is outside the scope of this document; see
-lex3.py, mode2.py and mode/*.py for examples. Some important points to note:
+lex.py, mode.py and mode/*.py for examples. Some important points to note:
 
     * Regexes are applied to only one line of the document at a time.
     * All regexes must match at least one character (the newline counts).
@@ -62,6 +67,8 @@ lex3.py, mode2.py and mode/*.py for examples. Some important points to note:
     * Regions of text which begin and end with recognizable tokens can be
       lexed using a different sub-grammar using RegionRule, etc. This nesting
       can be arbitrarily deep.
+    * sub-grammars can be dynamically specified in modes that provide one or
+      more OverridePatternRule objects.
 
 5. Indentation level detection
 
@@ -78,9 +85,9 @@ in the mode. At a minimum, a tabber must support the following methods:
     * region_added(self, p, lines)
     * region_removed(self, p1, p2)
 
-Tabber classes can often be tricky to implement correctly. tab2.Tabber provides
+Tabber classes can often be tricky to implement correctly. tab.Tabber provides
 a lot of base functionality that is probably useful; also, you may want to try
-looking at tab2.StackTabber, which provides even more base support.
+looking at tab.StackTabber, which provides even more base support.
 
 6. Tag matching
 
@@ -98,7 +105,7 @@ cases, here is how it works:
         * closetokens: tuple of lexical tokens which can be closetags
         * closetags:   dictionary mapping closetag strings to opentag strings
 
-    b. Also in the visecmode, create or instantiate actions who subclass
+    b. Also in the mode, create or instantiate actions who subclass
        method.CloseTag (e.g. method.CloseParen) and assign them the appropriate
        binding (e.g. '(').
 

README

@@ -17,7 +17,7 @@ others. The code is somewhat commented, although currently there is only one
 author. Buyer beware!
 
 Requirements:
-    1. python 2.3 or higher
+    1. python 2.4 or higher
     2. ncurses
     3. bash
 
@@ -72,9 +72,10 @@ Quick Start Guide:
         C-x C-f           open file in a new buffer
         C-x k             close the current buffer
 
-        C-c M-h           open a buffer listing all available commands/bindings
+        C-c M-h           open a buffer listing all available key bindings
-        M-h               get a help with a command by name
+        C-c M-?           open a buffer listing all available functions
-        M-?               get information about a key sequence
+        M-?               get a help with a command by name
+        M-h               get information about a key sequence
 
         C-x C-s           save your changes
         C-x C-c           quit
@@ -92,4 +93,4 @@ Quick Start Guide:
 
         b. comments in the source code
 
-Good luck!
+Good luck!