added textile-mode and mmm-mode. xpath stuff

[emacs-init.git] / mmm-mode-0.4.8 / mmm.info-2

This is mmm.info, produced by makeinfo version 4.2 from mmm.texinfo.

INFO-DIR-SECTION GNU Emacs Lisp
START-INFO-DIR-ENTRY
* MMM-Mode: (mmm).                 Multiple Major Modes for Emacs
END-INFO-DIR-ENTRY

   This is edition 0.4.8 of the MMM Mode Manual, last updated 9 March
2003. It documents version 0.4.8 of MMM Mode.

   Copyright 2000 Michael Abraham Shulman.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

\037
File: mmm.info,  Node: Mason,  Next: File Variables,  Prev: Supplied Classes,  Up: Supplied Classes

Mason: Perl in HTML
===================

   Mason is a syntax to embed Perl code in HTML and other documents.
See `http://www.masonhq.com' for more information.  The submode class
for Mason components is called `mason' and is loaded on demand from
`mmm-mason.el'.  The current Mason class is intended to correctly
recognize all syntax valid in Mason 0.896.  There are insertion keys
for most of the available syntax; use `mmm-insertion-help' (`C-c % h'
by default) with Mason on to get a list.

   If you want to have mason submodes automatically in all Mason files,
you can use automatic mode and filename associations; the details
depend on what you call your Mason components and what major mode you
use.  *Note Mode-Ext Classes::.  If you use an extension for your Mason
files that emacs does not automatically place in your preferred HTML
Mode, you will probably want to associate that extension with your HTML
Mode as well; *Note Choosing Modes: (emacs)Choosing Modes.  This also
goes for "special" Mason files such as autohandlers and dhandlers.

   The Perl mode used is controlled by the user: *Note Preferred
Modes::.  The default is to use CPerl mode, if present.  Unfortunately,
there are also certain problems with CPerl mode in submode regions.
(Not to say that the original perl-mode would do any better--it hasn't
been much tried.)  First of all, the first line of a Perl section is
usually indented as if it were a continuation line.  A fix for this is
to start with a semicolon on the first line.  The insertion key
commands do this whenever the Mason syntax allows it.

     <%perl>;
     print $var;
     </%perl>

   In addition, some users have reported that the CPerl indentation
sometimes does not work. This problem has not yet been tracked down,
however, and more data about when it happens would be helpful.

   Some people have reported problems using PSGML with Mason.  Adding
the following line to a `.emacs' file should suffice to turn PSGML off
and cause emacs to use a simpler HTML mode:

     (autoload 'html-mode "sgml-mode" "HTML Mode" t)

   Earlier versions of PSGML may require instead the following fix:

     (delete '("\\.html$" . sgml-html-mode) auto-mode-alist)
     (delete '("\\.shtml$" . sgml-html-mode) auto-mode-alist)

   Other users report using PSGML with Mason and MMM Mode without
difficulty.  If you don't have problems and want to use PSGML, you may
need to replace `html-mode' in the suggested code with
`sgml-html-mode'.  (Depending on your version of PSGML, this may not be
necessary.)  Similarly, if you are using XEmacs and want to use the
alternate HTML mode `hm--html-mode', replace `html-mode' with that
symbol.

   One problem that crops up when using PSGML with Mason is that even
ignoring the special tags and Perl code (which, as I've said, haven't
caused me any problems), Mason components often are not a complete SGML
document.  For instance, my autohandlers often say

     <body>
       <% $m->call_next %>
     </body>

   in which case the actual components contain no doctype declaration,
`<html>', `<head>', or `<body>', confusing PSGML.  One solution I've
found is to use the variable `sgml-parent-document' in such incomplete
components; try, for example, these lines at the end of a component.

     %# Local Variables:
     %# sgml-parent-document: ("autohandler" "body" nil ("body"))
     %# sgml-doctype: "/top/level/autohandler"
     %# End:

   This tells PSGML that the current file is a sub-document of the file
`autohandler' and is included inside a `<body>' tag, thus alleviating
its confusion.

\037
File: mmm.info,  Node: File Variables,  Next: Here-documents,  Prev: Mason,  Up: Supplied Classes

Elisp in a Local Variables List
===============================

   Emacs allows the author of a file to specify major and minor modes
to be used while editing that file, as well as specifying values for
other local Elisp variables, with a File Variables list.  *Note File
Variables: (emacs)File Variables.  Since file variables values are
Elisp objects (and with the `eval' special "variable", they are forms
to be evaluated), one might want to edit them in `emacs-lisp-mode'.
The submode class `file-variables' allows this, and is suitable for
turning on in a given file with `mmm-classes', or in all files with
`mmm-global-classes'.

\037
File: mmm.info,  Node: Here-documents,  Next: Javascript,  Prev: File Variables,  Up: Supplied Classes

Here-documents
==============

   One of the long-time standard syntaxes for outputting large amounts
of code (or text, or HTML, or whatever) from a script (notably shell
scripts and Perl scripts) is the here-document syntax:

     print <<END_HTML;
     <html>
       <head>
         <title>Test Page</title>
       </head>
       <body>
     END_HTML

   The `here-doc' submode class recognizes this syntax, and can even
guess the correct submode to use in many cases.  For instance, it would
put the above example in `html-mode', noticing the string `HTML' in the
name of the here-document.  If you use less than evocative
here-document names, or if the submode is recognized incorrectly for
any other reason, you can tell it explicitly what submode to use.

 - User Option: mmm-here-doc-mode-alist
     The value of this variable should be an alist, each element a cons
     pair associating a regular expression to a submode symbol.
     Whenever a here-document name matches one of these regexps, the
     corresponding submode is applied.  For example, if this variable
     contains the element `("CODE" . cc-mode)', then any here-document
     whose name contains the string `CODE' will be put in `cc-mode'.
     The value of this variable overrides any guessing that the
     `here-doc' submode class would do otherwise.

\037
File: mmm.info,  Node: Javascript,  Next: Embedded CSS,  Prev: Here-documents,  Up: Supplied Classes

Javascript in HTML
==================

   The submode class `html-js' allows for embedding Javascript code in
HTML documents.  It recognizes both this syntax:

     <script language="Javascript">
     function foo(...) {
        ...
     }
     </script>

   and this syntax:

     <input type="button" onClick="validate();">

   The mode used for Javascript regions is controlled by the user;
*Note Preferred Modes::.

\037
File: mmm.info,  Node: Embedded CSS,  Next: Embperl,  Prev: Javascript,  Up: Supplied Classes

CSS embedded in HTML
====================

   CSS (Cascading Style Sheets) can also be embedded in HTML.  The
`embedded-css' submode class recognizes this syntax:

     <style>
     h1 {
        ...
     }
     </style>

   It uses `css-mode' if present, `c++-mode' otherwise.  This can be
customized: *Note Preferred Modes::.

\037
File: mmm.info,  Node: Embperl,  Next: ePerl,  Prev: Embedded CSS,  Up: Supplied Classes

Embperl: More Perl in HTML
==========================

   Embperl is another syntax for embedding Perl in HTML.  See
`http://perl.apache.org/embperl' for more information.  The `embperl'
submode class recognizes most if not all of the Embperl embedding
syntax.  Its Perl mode is also controllable by the user; *Note
Preferred Modes::.

\037
File: mmm.info,  Node: ePerl,  Next: JSP,  Prev: Embperl,  Up: Supplied Classes

ePerl: General Perl Embedding
=============================

   Yet another syntax for embedding Perl is called ePerl.  See
`http://www.engelschall.com/sw/eperl/' for more information.  The
`eperl' submode class handles this syntax, using the Perl mode
specified by the user; *Note Preferred Modes::.

\037
File: mmm.info,  Node: JSP,  Next: RPM,  Prev: ePerl,  Up: Supplied Classes

JSP: Java Embedded in HTML
==========================

   JSP (Java Server Pages) is a syntax for embedding Java code in HTML.
The submode class `jsp' handles this syntax, using a Java mode
specified by the user; *Note Preferred Modes::.  The default is
`jde-mode' if present, otherwise `java-mode'.

\037
File: mmm.info,  Node: RPM,  Next: Noweb,  Prev: JSP,  Up: Supplied Classes

RPM Spec Files
==============

   `mmm-rpm.el' contains the definition of an MMM Mode submode class
for editing shell script sections within RPM (Redhat Package Manager)
spec files.  It is recommended for use in combination with
`rpm-spec-mode.el' by Stig Bjørlykke <stigb@tihlde.hist.no> and Steve
Sanbeg <sanbeg@dset.com>
(`http://www.xemacs.org/~stigb/rpm-spec-mode.el').

   Suggested setup code:

     (add-to-list 'mmm-mode-ext-classes-alist
                  '(rpm-spec-mode "\\.spec\\'" rpm-sh))

   Thanks to Marcus Harnisch <Marcus.Harnisch@gmx.net> for contributing
this submode class.

\037
File: mmm.info,  Node: Noweb,  Prev: RPM,  Up: Supplied Classes

Noweb literate programming
==========================

   `mmm-noweb.el' contains the definition of an MMM Mode submode class
for editing Noweb documents.  Most Noweb documents use \LaTeX for the
documentation chunks.  Code chunks in Noweb are document-specific, and
the mode may be set with a local variable setting in the document.  The
variable MMM-NOWEB-CODE-MODE controls the global code chunk mode. Since
Noweb files may have many languages in their code chunks, this mode
also allows setting the mode by specifying a mode in the first line or
two of a code chunk, using the normal Emacs first-line mode setting
syntax.  Note that this first-line mode setting only matches a single
word for the mode name, and does not support the variable name setting
of the generalized first file line syntax.


% -*- mode: latex; mmm-noweb-code-mode: c++; -*-
% First chunk delimiter!
@
\noweboptions{smallcode}

\title{Sample Noweb File}
\author{Joe Kelsey\\
\nwanchorto{mailto:bozo@bozo.bozo}{\tt bozo@bozo.bozo}}
\maketitle

@
\section{Introduction}
Normal noweb documentation for the required [[*]] chunk.
<<*>>=
// C++ mode here!
// We might list the program here, or simply included chunks.
<<myfile.cc>>
@ %def myfile.cc

@
\section{[[myfile.cc]]}
This is [[myfile.cc]].  MMM noweb-mode understands code quotes in
documentation.
<<myfile.cc>>=
// This section is indented separately from previous.
@ 

@
\section{A Perl Chunk}
We need a Perl chunk.
<<myfile.pl>>=
#!/usr/bin/perl
# -*- perl -*-
# Each differently named chunk is flowed separately.
@ 

\section{Finish [[myfile.cc]]}
When we resume a previously defined chunk, they are indented together.
<<myfile.cc>>=
// Pick up where we left off...
@

   The quoted code chunks inside documentation chunks are given the mode
found in the variable MMM-NOWEB-QUOTE-MODE, if set, or the value in
MMM-NOWEB-CODE-MODE otherwise.  Also, each quoted chunk is set to have
a unique name to prevent them from being indented as a unit.

   Suggested setup code:
     (mmm-add-mode-ext-class 'latex-mode "\\.nw\\'" 'noweb)
     (add-to-list 'auto-mode-alist '("\\.nw\\'" . latex-mode))

   In mmm-noweb buffers, each differently-named code chunk has a
different `:name', allowing all chunks with the same name to get
indented together.

   This mode also supplies special paragraph filling operations for use
in documentation areas of the buffer.  From a primary-mode
(`latex-mode, , emacs') region, pressing `C-c % C-q' will mark all
submode regions with word syntax (`mmm-word-other-regions'), fill the
current paragraph (`(fill-paragraph justify)'), and remove the syntax
markings (`mmm-undo-syntax-other-regions').

   Thanks to Joe Kelsey <joe@zircon.seattle.wa.us> for contributing this
class.

\037
File: mmm.info,  Node: Writing Classes,  Next: Indices,  Prev: Supplied Classes,  Up: Top

Writing Submode Classes
***********************

   Sometimes (perhaps often) you may want to use MMM with a syntax for
which it is suited, but for which no submode is supplied.  In such cases
you may have to write your own submode class.  This chapter briefly
describes how to write a submode class, from the basic to the advanced,
with examples.

* Menu:

* Basic Classes::               Writing a simple submode class.
* Paired Delimiters::           Matching paired delimiters.
* Region Placement::            Placing the region more accurately.
* Submode Groups::              Grouping several classes together.
* Calculated Submodes::         Deciding the submode at run-time.
* Calculated Faces::            Deciding the display face at run-time.
* Insertion Commands::          Inserting regions automatically.
* Region Names::                Naming regions for syntax grouping.
* Other Hooks::                 Running code at arbitrary points.
* Delimiters::                  Controlling delimiter overlays.
* Misc Keywords::               Other miscellaneous options.

\037
File: mmm.info,  Node: Basic Classes,  Next: Paired Delimiters,  Prev: Writing Classes,  Up: Writing Classes

Writing Basic Submode Classes
=============================

   Writing a submode class can become rather complex, if the syntax to
match is complicated and you want to take advantage of some of MMM
Mode's extra features.  But a simple submode class is not particularly
difficult to write.  This section describes the basics of writing
submode classes.

   Submode classes are stored in the variable `mmm-classes-alist'.
Each element of this list represents a single submode class.  For
convenience, the function `mmm-add-classes' takes a list of submode
classes and adds them all to this alist.  Each class is represented by a
list containing the class name--a symbol such as `mason' or
`html-js'--followed by pairs of keywords and arguments called a "class
specifier".  For example, consider the specifier for the submode class
`embedded-css':

     (mmm-add-classes
      '((embedded-css
         :submode css
         :face mmm-declaration-submode-face
         :front "<style[^>]*>"
         :back "</style>")))

   The name of the submode is `embedded-css', the first element of the
list.  The rest of the list consists of pairs of keywords (symbols
beginning with a colon) such as `:submode' and `:front', and arguments,
such as `css' and `"<style[^>]*>"'.  It is the keywords and arguments
that specify how the submode works.  The order of keywords is not
important; all that matters is the arguments that follow them.

   The three most important keywords are `:submode', `:front', and
`:back'.  The argument following `:submode' names the major mode to use
in submode regions.  It can be either a symbol naming a major mode,
such as `text-mode' or `c++-mode', or a symbol to look up in
`mmm-major-mode-preferences' (*note Preferred Modes::) such as `css',
as in this case.

   The arguments following `:front' and `:back' are regular expressions
(*note Regexps: (emacs)Regexps.) that should match the delimiter
strings which begin and end the submode regions.  In our example, CSS
regions begin with a `<style>' tag, possibly with parameters, and end
with a `</style>' tag.

   The argument following `:face' specifies the face (background color)
to use when `mmm-submode-decoration-level' is 2 (high coloring).  *Note
Region Coloring::, for a list of canonical available faces.

   There are many more possible keywords arguments.  In the following
sections, we will examine each of them and their uses in writing submode
classes.

\037
File: mmm.info,  Node: Paired Delimiters,  Next: Region Placement,  Prev: Basic Classes,  Up: Writing Classes

Matching Paired Delimiters
==========================

   A simple pair of regular expressions does not always suffice to
exactly specify the beginning and end of submode regions correctly.
For this reason, there are several other possible keyword/argument
pairs which influence the matching process.

   Many submode regions are marked by paired delimiters.  For example,
the tags used by Mason (*note Mason::) include `<%init>...</%init>' and
`<%args>...</%args>'.  It would be possible to write a separate submode
class for each type of region, but there is an easier way: the keyword
argument `:save-matches'.  If supplied and non-nil, it causes the
regular expression `:back', before being searched for, to be formatted
by replacing all strings of the form `~N' (where N is an integer) with
the corresponding numbered subexpression of the match for `:front'.  As
an example, here is an excerpt from the `here-doc' submode class.
*Note Here-documents::, for more information about this submode.

     :front "<<\\([a-zA-Z0-9_-]+\\)"
     :back "^~1$"
     :save-matches 1

   The regular expression for `:front' matches `<<' followed by a
string of one or more alphanumeric characters, underscores, and dashes.
The latter string, which happens to be the name of the here-document, is
saved as the first subexpression, since it is surrounded by `\(...\)'.
Then, because the value of `:save-matches' is present and non-nil, the
string `~1' is replaced in the value of `:back' by the name of the
here-document, thus creating a regular expression to match the correct
ending delimiter.

\037
File: mmm.info,  Node: Region Placement,  Next: Submode Groups,  Prev: Paired Delimiters,  Up: Writing Classes

Placing Submode Regions Precisely
=================================

   Normally, a submode region begins immediately after the end of the
string matching the `:front' regular expression and ends immediately
before the beginning of the string matching the `:back' regular
expression.  This can be changed with the keywords `:include-front' and
`:include-back'.  If their arguments are `nil', or they do not appear,
the default behavior is unchanged.  But if the argument of
`:include-front' (respectively, `:include-back') is non-nil, the
submode region will begin (respectively, end) immediately before
(respectively, after) the string matching the `:front' (respectively,
`:back') regular expression.  In other words, these keywords specify
whether or not the delimiter strings are _included_ in the submode
region.

   When `:front' and `:back' are regexps, the delimiter is normally
considered to be the entire matched region.  This can be changed using
the `:front-match' and `:back-match' keywords.  The values of the
keywords is a number specifying the submatch.  This defaults to zero
(specifying the whole regexp).

   Two more keywords which affect the placement of the region
`:front-offset' and `:back-offset', which both take integers as
arguments.  The argument of `:front-offset' (respectively,
`:back-offset') gives the distance in characters from the beginning
(respectively, ending) location specified so far, to the actual point
where the submode region begins (respectively, ends).  For example, if
`:include-front' is nil or unsupplied and `:front-offset' is 2, the
submode region will begin two characters after the end of the match for
`:front', and if `:include-back' is non-nil and `:back-offset' is -1,
the region will end one character before the end of the match for
`:back'.

   In addition to integers, the arguments of `:front-offset' and
`:back-offset' can be functions which are invoked to move the point
from the position specified by the matches and inclusions to the correct
beginning or end of the submode region, or lists whose elements are
either functions or numbers and whose effects are applied in sequence.
To help disentangle these options, here is another excerpt from the
`here-doc' submode class:

     :front "<<\\([a-zA-Z0-9_-]+\\)"
     :front-offset (end-of-line 1)
     :back "^~1$"
     :save-matches 1

   Here the value of `:front-offset' is the list `(end-of-line 1)',
meaning that from the end of the match for `:front', go to the end of
the line, and then one more character forward (thus to the beginning of
the next line), and begin the submode region there.  This coincides
with the normal behavior of here-documents: they begin on the following
line and go until the ending flag.

   If the `:back' should not be able to start a new submode region, set
the `:end-not-begin' keyword to non-nil.

\037
File: mmm.info,  Node: Submode Groups,  Next: Calculated Submodes,  Prev: Region Placement,  Up: Writing Classes

Defining Groups of Submodes
===========================

   Sometimes more than one submode class is required to accurately
reflect the behavior of a single type of syntax.  For example, Mason
has three very different types of Perl regions: blocks bounded by
matched tags such as `<%perl>...</%perl>', inline output expressions
bounded by `<%...%>', and single lines of code which simply begin with a
`%' character.  In cases like these, it is possible to specify an
"umbrella" class, to turn all these classes on or off together.

 - Function: mmm-add-group GROUP CLASSES
     The submode classes CLASSES, which should be a list of lists,
     similar to what might be passed to `mmm-add-classes', are added
     just as by that function.  Furthermore, another class named GROUP
     is added, which encompasses all the classes in CLASSES.

   Technically, an group class is specified with a `:classes' keyword
argument, and the subsidiary classes are given a non-nil `:private'
keyword argument to make them invisible.  But in general, all you should
ever need to know is how to invoke the function above.

 - Function: mmm-add-to-group GROUP CLASSES
     Adds a list of classes to an already existing group.  This can be
     used, for instance, to add a new quoting definition to HTML-JS
     using this example to add the quote characters "%=%":

          (mmm-add-to-group 'html-js '((js-html
                                     :submode javascript
                                     :face mmm-code-submode-face
                                     :front "%=%"
                                     :back "%=%"
                                     :end-not-begin t)))

\037
File: mmm.info,  Node: Calculated Submodes,  Next: Calculated Faces,  Prev: Submode Groups,  Up: Writing Classes

Calculating the Correct Submode
===============================

   In most cases, the author of a submode class will know in advance
what major mode to use, such as `text-mode' or `c++-mode'.  If there
are multiple possible modes that the user might desire, then
`mmm-major-mode-preferences' should be used (*note Preferred Modes::).
The function `mmm-set-major-mode-preferences' can be used, with a third
argument, to ensure than the mode is present.

   In some cases, however, the author has no way of knowing in advance
even what language the submode region will be in.  The `here-doc' class
is one of these.  In such cases, instead of the `:submode' keyword, the
`:match-submode' keyword must be used.  Its argument should be a
function, probably written by the author of the submode class, which
calculates what major mode each region should use.

   It is invoked immediately after a match is found for `:front', and
is passed one argument: a string representing the front delimiter.
Normally this string is simply whatever was matched by `:front', but
this can be changed with the keyword `:front-form' (*note
Delimiters::).  The function should then return a symbol that would be
a valid argument to `:submode': either the name of a mode, or that of a
language to look up a preferred mode.  If it detects an invalid
match--for example, the user has specified a mode which is not
available--it should `(signal 'mmm-no-matching-submode nil)'.

   Since here-documents can contain code in any language, the
`here-doc' submode class uses `:match-submode' rather than `:submode'.
The function it uses is `mmm-here-doc-get-mode', defined in
`mmm-sample.el', which inspects the name of the here-document for flags
indicating the proper mode.  For example, this code should probably be
in `perl-mode' (or `cperl-mode'):

     print <<PERL;
     s/foo/bar/g;
     PERL

   This function is also a good example of proper elisp hygiene: when
writing accessory functions for a submode class, they should usually be
prefixed with `mmm-' followed by the name of the submode class, to
avoid namespace conflicts.

\037
File: mmm.info,  Node: Calculated Faces,  Next: Insertion Commands,  Prev: Calculated Submodes,  Up: Writing Classes

Calculating the Correct Highlight Face
======================================

   As explained in *Note Basic Classes::, the keyword `:face' should be
used to specify which of the standard submode faces (*note Region
Coloring::) a submode region should be highlighted with under high
decoration.  However, sometimes the function of a region can depend on
the form of the delimiters as well.  In this case, a more flexible
alternative to `:face' is `:match-face'.  Its value can be a function,
which is called with one argument--the form of the front delimiter, as
with `:match-submode'--and should return the face to use.  A more
common value for `:match-face' is an association list, a list of pairs
`(DELIM . FACE)', each specifying that if the delimiter is DELIM, the
corresponding region should be highlighted with FACE.  For example,
here is an excerpt from the `embperl' submode class:

     :submode perl
     :front "\\[\\([-\\+!\\*\\$]\\)"
     :back "~1\\]"
     :save-matches 1
     :match-face (("[+" . mmm-output-submode-face)
                  ("[-" . mmm-code-submode-face)
                  ("[!" . mmm-init-submode-face)
                  ("[*" . mmm-code-submode-face)
                  ("[$" . mmm-special-submode-face))

   Thus, regions beginning with `[+' are highlighted as output
expressions, which they are, while `[-' and `[*' regions are
highlighted as simple executed code, and so on.  Note that
MMM-SUBMODE-DECORATION-LEVEL must be set to 2 (high decoration) for
different faces to be displayed.

\037
File: mmm.info,  Node: Insertion Commands,  Next: Region Names,  Prev: Calculated Faces,  Up: Writing Classes

Specifying Insertion Commands
=============================

   As described in *Note Insertion::, submode classes can specify key
sequences which automatically insert submode regions, with delimiters
already in place.  This is done by the keyword argument `:insert'.  Its
value should be a list, each element of which specifies a single
insertion key sequence.  As an example, consider the following insertion
key sequence specifier, from the `embperl' submode class:

     (?p embperl "Region Type (Character): "
         @ "[" str @ " " _ " " @ str "]" @)

   As you can see, the specifier is a list.  The first element of the
list is the character `p'.  (The question mark tells Emacs that this is
a character object, not a one-character symbol.)  In general, the first
element can be any key, including both characters such as `?p' and
function keys such as `return'.  It can also be a dotted pair in which
the first element is a modifier symbol such as `meta', and the second
is a character or function key.  The use of any other modifier than
meta is discouraged, as `mmm-insert-modifiers' is sometimes set to
\(control), and other modifiers are not very portable.  The second
element is a symbol identifying this key sequence.  The third element
is a prompt string which is used to ask the user for input when this
key sequence is invoked.  If it is nil, the user is not prompted.

   The rest of the list specifies the actual text to be inserted, where
the submode region and delimiters should be, and where the point should
end up.  (Actually, this string is simply passed to `skeleton-insert';
see the documentation string of that function for more details on the
permissible elements of such a skeleton.)  Strings and variable names
are inserted and interpolated.  The value entered by the user when
prompted, if any, is available in the variable `str'.  The final
location of the point (or the text around which the region is to be
wrapped) is marked with a single underscore `_'.  Finally, the @-signs
mark the delimiters and submode regions.  There should be four @-signs:
one at the beginning of the front delimiter, one at the beginning of
the submode region, one at the end of the submode region, and one at
the end of the back delimiter.

   The above key sequence, bound by default to `C-c % p', always
prompts the user for the type of region to insert.  It can also be
convenient to have separate key sequences for each type of region to be
inserted, such as `C-c % +' for `[+...+]' regions, `C-c % -' for
`[-...-]' regions, and so on.  So that the whole skeleton doesn't have
to be written out half a dozen times, there is a shortcut syntax, as
follows:

     (?+ embperl+ ?p . "+")

   If the key sequence specification is a dotted list with four
elements, as this example is, it means to use the skeleton defined for
the key sequence given as the third element (`?p'), but to pass it the
fourth (dotted) element (`"+"') as the `str' variable; the user is not
prompted.

\037
File: mmm.info,  Node: Region Names,  Next: Other Hooks,  Prev: Insertion Commands,  Up: Writing Classes

Giving Names to Submode Regions for Grouping
============================================

   Submode regions can be given "names" which are used for grouping.
Names are always strings and are compared as strings.  Regions with the
same name are considered part of the same chunk of code.  This is used
by the syntax and fontification functions.  Unnamed regions are not
grouped with any others.

   By default, regions are nameless, but with the `:match-name' keyword
argument a name can be supplied.  This argument must be a string or a
function.  If it is a function, it is passed a string representing the
front delimiter found, and must return the name to use.  If it is a
string, it is used as-is for the name, unless `:save-name' has a
non-nil value, in which case expressions such as `~1' are substituted
with the corresponding matched subexpression from `:front'.  This is
the same as how `:back' is interpreted when `:save-matches' is non-nil.

   As a special optimization for region insertion (*note Insertion
Commands::), the argument `:skel-name' can be set to a non-nil value,
in which case the insertion code will use the user-prompted string
value as the region name, instead of going through the normal matching
procedure.

\037
File: mmm.info,  Node: Other Hooks,  Next: Delimiters,  Prev: Region Names,  Up: Writing Classes

Other Hooks into the Scanning Process
=====================================

   Sometimes, even the flexibility allowed by all the keyword arguments
discussed so far is insufficient to correctly match submode regions.
There are several other keyword arguments which accept custom functions
to be invoked at various points in the MMM-ification process.

   First of all, the arguments of `:front' and `:back', in addition to
regular expressions, can be themselves functions.  Such functions
should "act like" a regular expression search: they should start
searching at point, take one argument as a limit for the search, and
return its result by setting the match data (presumably by calling some
regexp matching function).

   This is rarely necessary, however, because often all that is needed
is a simple regexp search, followed by some sort of verification.  The
keyword arguments `:front-verify' and `:back-verify', if supplied, may
be functions which are invoked after a match is found for `:front' or
`:back', respectively, and should inspect the match data (such as with
`match-string') and return non-nil if a submode region should be begun
at this match, nil if this match should be ignored and the search
continue after it.

   The keyword argument `:creation-hook', if supplied, should be a
function that is invoked whenever a submode region of this class is
created, with point at the beginning of the new region.  This can be
used, for example, to set local variables appropriately.

   Finally, the entire MMM-ification process has a "back door" which
allows class authors to take control of the entire thing.  If the
keyword argument `:handler' is supplied, it overrides any other
processing and is called, and passed all other class keyword arguments,
instead of `mmm-ify' to create submode regions.  If you need to write a
handler function, I suggest looking at the source for `mmm-ify' to get
an idea of what must be done.

\037
File: mmm.info,  Node: Delimiters,  Next: Misc Keywords,  Prev: Other Hooks,  Up: Writing Classes

Controlling the Delimiter Regions and Forms
===========================================

   MMM also makes overlays for the delimiter regions, to keep track of
their position and form.  Normally, the front delimiter overlay starts
at the beginning of the match for `:front' and ends at the beginning of
the submode region overlay, while the back delimiter overlay starts at
the end of the submode region overlay and ends at the end of the match
for `:back'.  You can supply offsets from these positions using the
keyword arguments `:front-delim' and `:back-delim', which take values
of the same sort as `:front-offset' and `:back-offset'.

   In addition, the delimiter regions can be in a major mode of their
own.  There are usually only two meaningful modes to use: the primary
mode or a non-mode like fundamental-mode.  These correspond to the
following two situations:

   * If the delimiter syntax which specifies the submode regions is
     something _added to_ the syntax of the primary mode by a
     pre-interpreter, then the delimiter regions should be in a
     non-mode.  This is the case, for example, with all server-side
     HTML script extensions, such as *Note Mason::, *Note Embperl::,
     and *Note ePerl::.  It is also the case for literate programming
     such as *Note Noweb::.  This is the default behavior.  The
     non-mode used is controlled by the variable `mmm-delimiter-mode',
     which defaults to fundamental-mode.

   * If, on the other hand, the delimiter syntax and inclusion of
     different modes is an _intrinsic part_ of the primary mode, then
     the delimiter regions should remain in the primary mode.  This is
     the case, for example, with *Note Embedded CSS::, and *Note
     Javascript::, since the `<style>' and `<script>' tags are
     perfectly valid HTML.  In this case, you should give the keyword
     parameter `:delimiter-mode' with a value of `nil', meaning to use
     the primary mode.

   The keyword parameter `:delimiter-mode' can be given any major mode
as an argument, but the above two situations should cover the vast
majority of cases.

   The delimiter regions can also be highlighted, if you wish.  The
keyword parameters `:front-face' and `:back-face' may be faces
specifying how to highlight these regions under high decoration.  Under
low decoration, the value of the variable `mmm-delimiter-face' is used
(by default, nothing), and of course under no decoration there is no
coloring.

   Finally, for each submode region overlay, MMM Mode stores the "form"
of the front and back delimiters, which are regular expressions that
match the delimiters.  At present these are not used for much, but in
the future they may be used to help with automatic updating of regions
as you type.  Normally, the form stored is the result of evaluating the
expression `(regexp-quote (match-string 0))' after each match is found.

   You can customize this with the keyword argument `:front-form'
(respectively, `:back-form').  If it is a string, it is used verbatim
for the front (respectively, back) form.  If it is a function, that
function is called and should inspect the match data and return the
regular expression to use as the form.

   In addition, the form itself can be set to a function, by giving a
one-element list containing only that function as the argument to
`:front-form' or `:back-form'.  Such a function should take 1-2
arguments.  The first argument is the overlay to match the delimiter
for.  If the second is non-nil, it means to insert the delimiter and
adjust the overlay; if nil it means to match the delimiter and return
the result in the match data.

\037
File: mmm.info,  Node: Misc Keywords,  Prev: Delimiters,  Up: Writing Classes

Miscellaneous Other Keyword Arguments
=====================================

   You can specify whether delimiter searches should be case-sensitive
with the keyword argument `:case-fold-search'.  It defaults to `t',
meaning that case should be ignored.  See the documentation for the
variable `case-fold-search'.

\037
File: mmm.info,  Node: Indices,  Prev: Writing Classes,  Up: Top

Indices
*******

* Menu:

* Concept Index::               Index of MMM Mode Concepts.
* Function Index::              Index of functions and variables.
* Keystroke Index::             Index of key bindings in MMM Mode.

\037
File: mmm.info,  Node: Concept Index,  Next: Function Index,  Prev: Indices,  Up: Indices

Concept Index
=============

* Menu:

* class, mmm-ification by:               Interactive.
* classes, submode:                      Submode Classes.
* clearing submode regions:              Re-parsing.
* customizing submode faces:             Region Coloring.
* default major mode:                    Basic Concepts.
* default submode face:                  Region Coloring.
* disabling mmm mode:                    Enabling MMM Mode.
* dominant major mode:                   Basic Concepts.
* enabling mmm mode:                     Enabling MMM Mode.
* faces, submode:                        Region Coloring.
* global mmm mode:                       Global Mode.
* history of interactive mmm-ification:  Interactive.
* hook, major mode:                      Major Mode Hook.
* interactive mmm-ification:             Interactive.
* interactive mmm-ification, history of: Interactive.
* key bindings in mmm mode:              MMM Mode Keys.
* major mode hook:                       Major Mode Hook.
* major mode, default:                   Basic Concepts.
* major mode, dominant:                  Basic Concepts.
* minor mode, mmm:                       MMM Minor Mode.
* mmm global mode:                       Global Mode.
* mmm minor mode:                        MMM Minor Mode.
* mmm mode key bindings:                 MMM Mode Keys.
* mmm mode, disabling:                   Enabling MMM Mode.
* mmm mode, enabling:                    Enabling MMM Mode.
* mmm mode, turning off:                 Enabling MMM Mode.
* mmm mode, turning on:                  Enabling MMM Mode.
* mmm-ification:                         Basic Concepts.
* mmm-ification by class:                Interactive.
* mmm-ification by regexp:               Interactive.
* mmm-ification by region:               Interactive.
* mmm-ification, interactive:            Interactive.
* mmm-ification, interactive history:    Interactive.
* mmm-mode, overview of:                 Overview.
* mode, mmm global:                      Global Mode.
* mode, mmm minor:                       MMM Minor Mode.
* overlays, submode:                     Basic Concepts.
* overview of mmm-mode:                  Overview.
* parsing submode regions:               Re-parsing.
* re-parsing submode regions:            Re-parsing.
* regexp, mmm-ification by:              Interactive.
* region, mmm-ification by:              Interactive.
* regions, submode:                      Basic Concepts.
* regions, submode, clearing:            Re-parsing.
* regions, submode, re-parsing:          Re-parsing.
* simple submode classes:                Basic Classes.
* submode classes:                       Submode Classes.
* submode classes, simple:               Basic Classes.
* submode faces:                         Region Coloring.
* submode overlays:                      Basic Concepts.
* submode regions:                       Basic Concepts.
* submode regions, clearing:             Re-parsing.
* submode regions, re-parsing:           Re-parsing.
* turning off mmm mode:                  Enabling MMM Mode.
* turning on mmm mode:                   Enabling MMM Mode.

\037
File: mmm.info,  Node: Function Index,  Next: Keystroke Index,  Prev: Concept Index,  Up: Indices

Function and Variable Index
===========================

* Menu:

* mmm-:                                  Hooks.
* mmm-add-group:                         Submode Groups.
* mmm-add-mode-ext-class:                Mode-Ext Classes.
* mmm-add-to-group:                      Submode Groups.
* mmm-classes:                           File Classes.
* mmm-clear-history:                     Interactive.
* mmm-get-class-parameter:               Changing Classes.
* mmm-global-classes:                    Global Classes.
* mmm-global-mode:                       Global Mode.
* mmm-here-doc-mode-alist:               Here-documents.
* mmm-insertion-help:                    MMM Mode Keys.
* mmm-interactive-history:               Interactive.
* mmm-major-mode-hook:                   Major Mode Hook.
* mmm-major-mode-preferences:            Preferred Modes.
* mmm-mode:                              Enabling MMM Mode.
* mmm-mode-ext-classes-alist:            Mode-Ext Classes.
* mmm-mode-hook:                         Hooks.
* mmm-mode-off:                          Enabling MMM Mode.
* mmm-mode-on:                           Enabling MMM Mode.
* mmm-mode-prefix-key:                   Key Bindings.
* mmm-mode-string:                       Mode Line.
* mmm-never-modes:                       Global Mode.
* mmm-save-local-variables:              Local Variables.
* mmm-set-class-parameter:               Changing Classes.
* mmm-set-major-mode-preferences:        Preferred Modes.
* mmm-submode-decoration-level:          Region Coloring.
* mmm-submode-mode-line-format:          Mode Line.
* mmm-use-old-command-keys:              Key Bindings.

\037
File: mmm.info,  Node: Keystroke Index,  Prev: Function Index,  Up: Indices

Keystroke Index
===============

* Menu:

* C-c % C-%:                             Re-parsing.
* C-c % C-5:                             Re-parsing.
* C-c % C-b:                             Re-parsing.
* C-c % C-c:                             Interactive.
* C-c % C-g:                             Re-parsing.
* C-c % C-k:                             Re-parsing.
* C-c % C-r:                             Interactive.
* C-c % C-x:                             Interactive.
* C-c % h:                               MMM Mode Keys.