From efadf61be54ebdd4f52f2192ff85c12a90d56504 Mon Sep 17 00:00:00 2001 From: moculus Date: Mon, 17 Mar 2008 07:46:20 +0000 Subject: [PATCH] doc updates --HG-- branch : pmacs2 --- MODES | 33 ++++++++++++++++++++------------- README | 11 ++++++----- 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/MODES b/MODES index 223d76b..e1717c3 100644 --- a/MODES +++ b/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 -keys should apply which actions, how the buffer should be highlighted, how the -buffer should be indented, and any other per-buffer configuration. The default -mode ("Fundamental") provides the base functionality which all other modes -inherit. +Pmacs uses modes to determine what which keys should apply which actions, how +the buffer should be highlighted, how the buffer should be indented, and any +other per-buffer configuration. The default mode ("Fundamental") provides the +base functionality which all other modes 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 -run the standard mode initialization (including building the default bindings +Modes subclass mode.Fundamental, and they call mode.Fundamental.__init__ to run +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 -of at least a foreground color and a background color. +defined by application.colors, a dictionary mapping token-names to a tuple +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. '('). diff --git a/README b/README index 67d6be6..4358ace 100644 --- a/README +++ b/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 - M-h get a help with a command by name - M-? get information about a key sequence + C-c M-h open a buffer listing all available key bindings + C-c M-? open a buffer listing all available functions + 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! \ No newline at end of file +Good luck!