This document is designed to be a quick (and incomplete) description of how
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.

2. Where do they come from?

All modes are loaded and installed in application.py. It would be nice if there
was a configuration file where you could add your own modes, but there isn't.
Loading a module involves the following (in Application.__init__):

    
    self.modes['foo'] = package.Foo

    # ...

    self.mode_paths['/some/full/path']   = 'foo'
    self.mode_basenames['some-filename'] = 'foo'
    self.mode_extensions['.foo']         = 'foo'
    self.mode_detection['foo']           = 'foo'

The last is for detecting scripts using the "#!/usr/bin/foo" syntax.

3. How do they work?

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
dictionary); they can later modify or overwrite this dictionary if they choose.