[elpa] master 447eb61 110/433: Wrote about changing key bindings and local variables.

[Dmitry Gutov]

branch: master
commit 447eb617a4ec160467210b0ba346d456619a6356
Author: mas <mas>
Commit: mas <mas>

    Wrote about changing key bindings and local variables.
    Copied info from documentation of `mmm-classes-alist'.
---
 mmm.texinfo | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 178 insertions(+), 2 deletions(-)

diff --git a/mmm.texinfo b/mmm.texinfo
index 7544923..f22c1d9 100644
--- a/mmm.texinfo
+++ b/mmm.texinfo
@@ -102,6 +102,7 @@ Customizing MMM Mode
 * Local Variables::             What local variables are saved for submodes.
 * Changing Classes::            Changing the supplied submode classes.
 * Hooks::                       How to make MMM Mode run your code.
+* Writing Classes::             Writing your own submode classes.
 
 Supplied Submode Classes
 
@@ -908,22 +909,98 @@ eliminate the indicator entirely, set this variable to 
the empty string.
 @comment  node-name,  next,  previous,  up
 @chapter Customizing the MMM Mode Key Bindings
 
+The default MMM Mode key bindings are explained in @ref{MMM Mode Keys},
+and in @ref{Insertion}.  There are a couple of ways to customize these
+bindings.
+
address@hidden mmm-mode-prefix-key
+The value of this variable (default is @kbd{C-c %}) should be a key
+sequence to use as the prefix for the MMM Mode keymap.  Minor modes
+typically use @kbd{C-c} followed by a punctuation character, but you can
+change it to any user-available key sequence.  To have an effect, this
+variable should be set before MMM Mode is loaded.
address@hidden defopt
+
address@hidden mmm-use-old-command-keys
+When this variable is @code{nil}, MMM Mode commands use the control
+modifier and insertion keys no modifier.  Any other value switches the
+two, so that @code{mmm-parse-buffer}, for example, is bound to @kbd{C-c
+% b}, while perl-section insertion in the Mason class is bound to
address@hidden % C-p}.  This variable should be set before MMM Mode is loaded
+to have an effect.
address@hidden defopt
+
+When MMM is loaded, it uses the value of @code{mmm-use-old-command-keys}
+to set the values of the variables @code{mmm-command-modifiers} and
address@hidden, so if you prefer you can set these
+variables instead.  They should each be a list of key modifiers, such as
address@hidden(control)} or @code{()}.  The Meta modifier is used in some of the
+command and insertion keys, so it should not be used, and the Shift
+modifier is not particularly portable between Emacsen---if it works for
+you, feel free to use it.  Other modifiers, such as Hyper and Super, are
+not universally available, but are valid when present.
 
 
 @node Local Variables, Changing Classes, Key Bindings, Top
 @comment  node-name,  next,  previous,  up
 @chapter Changing Saved Local Variables
 
+A lot of the functionality of MMM Mode---that which makes the major mode
+appear to change---is implemented by saving and restoring the values of
+local variables, or pseudo-variables.  You can customize what variables
+are saved, and how, with the following variable.
+
address@hidden mmm-save-local-variables
+At its simplest, this is a list each of whose elements is a buffer-local
+variable whose value is saved and restored for each major mode.  Each
+elements can also, however, be a list whose first element is the
+variable symbol and whose subsequent elements specify how and where the
+variable is to be saved.  The second element of the list, if present,
+should be one of the symbols @code{global}, @code{buffer}, or
address@hidden  If not present, the default value is @code{global}.  The
+third element, if present, should be a list of major mode symbols in
+which to save the variable.  In the list form, the variable symbol
+itself can be replaced with a cons cell of two functions, one to get the
+value and one to set the value.  This is called a ``pseudo-variable''.
address@hidden defvar
+
+Globally saved variables are the same in all (MMM-controlled) buffers
+and submode regions of each major mode listed in the third argument, or
+all major modes if it is @code{t} or not present.  Buffer-saved
+variables are the same in all submode regions of a given major mode in
+each buffer, and region-saved variables can be different for each
+submode region.
+
+Pseudo-variables are used, for example, to save and restore the syntax
+table (@pxref{Syntax, , , emacs, The Emacs Manual}) and mode keymaps
+(@pxref{Keymaps, , , emacs, The Emacs Manual}).
 
 
 @node Changing Classes, Hooks, Local Variables, Top
 @comment  node-name,  next,  previous,  up
 @chapter Changing the Supplied Submode Classes
 
+If you need to use MMM with a syntax for which a submode class is not
+supplied, and you have some facility with Emacs Lisp, you can write your
+own; see @ref{Writing Classes}.  However, sometimes you will only want
+to make a slight change to one of the supplied submode classes.  You can
+do this, after that class is loaded, with the following functions.
+
address@hidden mmm-set-class-parameter @var{class} @var{param} @var{value}
+Set the value of the keyword parameter @var{param} of the submode class
address@hidden to @var{value}.  @xref{Writing Classes}, for an explanation
+of the meaning of each keyword parameter.  This creates a new parameter
+if one is not already present in the class.
address@hidden defun
+
address@hidden mmm-get-class-parameter @var{class} @var{param}
+Get the value of the keyword parameter @var{param} for the submode class
address@hidden  Returns @code{nil} if there is no such parameter.
address@hidden defun
 
 
 
address@hidden Hooks, Mason, Changing Classes, Top
address@hidden Hooks, Writing Classes, Changing Classes, Top
 @comment  node-name,  next,  previous,  up
 @chapter Hooks Provided by MMM Mode
 
@@ -961,7 +1038,106 @@ set for supplied submode classes with 
@code{mmm-set-class-parameter};
 @ref{Changing Classes}.
 
 
address@hidden Mason, Eval-Elisp, Hooks, Top
address@hidden Writing Classes, Mason, Hooks, Top
address@hidden  node-name,  next,  previous,  up
address@hidden Writing Your Own Submode Classes
+
+This is copied from the documentation of @code{mmm-classes-alist} and
+serves as a good summary.  An introduction/tutorial would be nice,
+however.  This should probably have a number of subsections.
+
+Each element of @code{mmm-classes-alist} looks like (CLASS . ARGS) where
+CLASS is a symbol representing the submode class and ARGS is a list of
+keyword arguments, called a "class specifier". There are a large number
+of accepted keyword arguments.
+
+The argument CLASSES, if supplied, must be a list of other submode
+classes (or class specifiers), representing other classes to call.
+FACE, if supplied, overrides FACE arguments to these classes, but all
+other arguments to this class are ignored.
+
+The argument HANDLER, if supplied, overrides any other processing. It
+must be a function, and all the arguments are passed to it as
+keywords, and it must do everything. See `mmm-ify' for what sorts of
+things it must do. This back-door interface should be cleaned up.
+
+The argument FACE, if supplied, overrides `mmm-default-submode-face'
+in specifying the display face of the submode regions. It must be a
+valid display face.
+
+If neither CLASSES nor HANDLER are supplied, either SUBMODE or
+MATCH-SUBMODE must be.  SUBMODE specifies the submode to use for the
+submode regions, a symbol such as `cperl-mode' or `emacs-lisp-mode',
+while MATCH-SUBMODE must be a function to be called immediately after
+a match is found for FRONT, which is passed one argument, the form of
+the front delimiter (found from FRONT-FORM, below), and return a
+symbol such as SUBMODE would be set to.
+
+FRONT and BACK are the means to find the submode regions, and can be
+either buffer positions \(number-or-markers), regular expressions, or
+functions. If they are absolute buffer positions, only one submode
+region is created, from FRONT to BACK. This is generally not used in
+named classes. (Unnamed classes are created by interactive commands in
address@hidden).
+
+If FRONT is a regexp, then that regexp is searched for, and the end of
+its match, plus FRONT-OFFSET, becomes the beginning of the submode
+region. If FRONT is a function, that function is called instead, and
+must act somewhat like a search, in that it should start at point,
+take one argument as a search bound, and set the match data. A similar
+pattern is followed for BACK, save that the end of the submode region
+becomes the beginning of its match, plus BACK-OFFSET. FRONT- and
+BACK-OFFSET default to 0.
+
+FRONT-VERIFY and BACK-VERIFY, if supplied, must be functions that
+inspect the match data to see if a match found by FRONT or BACK
+respectively is valid.
+
+If SAVE-MATCHES is supplied, it must be a number, and means to format
+BACK, if it is a regexp, by replacing strings of the form @samp{~N} by
+the corresponding value of @code{(match-string n)} after matching FRONT,
+where N is between 0 and SAVE-MATCHES.
+
address@hidden and @var{back-form}, if given, must supply a regexp
+used to match the @emph{actual} delimiter.  If they are strings, they
+are used as-is.  If they are functions, they are called and must inspect
+the match data.  If they are lists, their @code{car} is the delimiter.
+The default for both is @code{(regexp-quote (match-string 0))}.
+
+The last case---them being a list---is usually used to set the delimiter
+to a function.  Such a function must take 1-2 arguments, the first being
+the overlay in question, and the second meaning to insert the delimiter
+and adjust the overlay rather than just matching the delimiter.  See
address@hidden, @code{mmm-match-back}, and
address@hidden
+
address@hidden, if specified, controls whether the search is
+case-insensitive. See `case-fold-search'. It defaults to `t'.
+
+CREATION-HOOK, if specified, should be a function which is run
+whenever a submode region is created, with point at the beginning of
+the new region.  One use for it is to set region-saved local variables
+(see `mmm-save-local-variables').
+
+INSERT specifies the keypress insertion spec for such submode regions.
+INSERT's value should be list of elements of the form (KEY NAME .
+SPEC). Each KEY should be either a character, a function key symbol, or
+a dotted list (MOD . KEY) where MOD is a symbol for a modifier key. The
+use of any other modifier than meta is discouraged, as
+`mmm-insert-modifiers' defaults to (control), and other modifiers are
+not very portable. Each NAME should be a symbol representing the
+insertion for that key. Each SPEC can be either a skeleton, suitable for
+passing to `skeleton-insert' to create a submode region, or a dotted
+pair (OTHER-KEY . ARG) meaning to use the skeleton defined for OTHER-KEY
+but pass it the argument ARG as the `str' variable, possible replacing a
+prompt string. Skeletons for insertion should have the symbol `_' where
+point (or wrapped text) should go, and the symbol `@' in four different
+places: at the beginning of the front delimiter, the beginning of the
+submode region, the end of the submode region, and the end of the back
+delimiter.
+
+
address@hidden Mason, Eval-Elisp, Writing Classes, Top
 @comment  node-name,  next,  previous,  up
 @chapter Mason: Perl in HTML