2108 lines
87 KiB
Text
2108 lines
87 KiB
Text
\input texinfo
|
||
@c %**start of header
|
||
@setfilename mmm.info
|
||
@settitle MMM Mode Manual
|
||
@c %**end of header
|
||
@syncodeindex vr fn
|
||
@set MASON_VERSION 0.896
|
||
|
||
@dircategory GNU Emacs Lisp
|
||
@direntry
|
||
* MMM-Mode: (mmm). Multiple Major Modes for Emacs
|
||
@end direntry
|
||
|
||
@ifinfo
|
||
|
||
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.
|
||
|
||
@ignore
|
||
Permission is granted to process this file through TeX and print the
|
||
results, provided the printed document carries a copying permission
|
||
notice identical to this one except for the removal of this paragraph
|
||
(this paragraph not being relevant to the printed manual).
|
||
|
||
@end ignore
|
||
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.
|
||
|
||
@end ifinfo
|
||
|
||
@titlepage
|
||
@title MMM Mode Manual
|
||
@subtitle Multiple Major Modes for Emacs
|
||
@author Michael Abraham Shulman
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
Copyright @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.
|
||
|
||
@end titlepage
|
||
|
||
@ifinfo
|
||
@node Top, Overview, (dir), (dir)
|
||
@top MMM Mode
|
||
|
||
MMM Mode is a minor mode for Emacs which allows Multiple Major Modes to
|
||
coexist in a single buffer.
|
||
|
||
@end ifinfo
|
||
|
||
@menu
|
||
* Overview:: An overview and introduction to MMM Mode.
|
||
* Basics:: The basics of how to use it.
|
||
* Customizing:: Customizing how it works to your needs.
|
||
* Supplied Classes:: The supplied submode classes.
|
||
* Writing Classes:: Writing your own submode classes.
|
||
* Indices:: Just that.
|
||
|
||
@detailmenu
|
||
--- The Detailed Node Listing ---
|
||
|
||
Overview of MMM Mode
|
||
|
||
* Basic Concepts:: A simple explanation of how it works.
|
||
* Installation:: How to install MMM Mode.
|
||
* Quick Start:: Getting started using MMM Mode quickly.
|
||
|
||
MMM Mode Basics
|
||
|
||
* MMM Minor Mode:: The Emacs minor mode that manages it all.
|
||
* Submode Classes:: What they are and how to use them.
|
||
* Selecting Classes:: How MMM Mode knows what classes to use.
|
||
* Insertion:: Inserting new submode regions automatically.
|
||
* Re-parsing:: Re-scanning for submode regions.
|
||
* Interactive:: Adding submode regions manually.
|
||
* Global Mode:: Turning MMM Mode on automatically.
|
||
|
||
The MMM Minor Mode
|
||
|
||
* Enabling MMM Mode:: Turning MMM Mode on and off.
|
||
* MMM Mode Keys:: Default key bindings in MMM Mode.
|
||
|
||
How MMM Mode selects submode classes
|
||
|
||
* File Classes:: Classes for a single file.
|
||
* Mode-Ext Classes:: Classes for a given mode or extension.
|
||
* Global Classes:: Classes for all MMM Mode buffers.
|
||
|
||
MMM Global Mode
|
||
|
||
* Major Mode Hook:: Using MMM's Major Mode Hook
|
||
|
||
Customizing MMM Mode
|
||
|
||
* Region Coloring:: Changing or removing background colors.
|
||
* Preferred Modes:: Choosing which major modes to use.
|
||
* Mode Line:: What is displayed in the mode line.
|
||
* Key Bindings:: Customizing the MMM Mode key bindings.
|
||
* 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.
|
||
|
||
Supplied Submode Classes
|
||
|
||
* Mason:: Mason server-side Perl in HTML.
|
||
* File Variables:: Elisp code in File Variables.
|
||
* Here-documents:: Code in shell and Perl here-documents.
|
||
* Javascript:: Javascript embedded in HTML.
|
||
* Embedded CSS:: CSS Styles embedded in HTML.
|
||
* Embperl:: Another syntax for Perl in HTML.
|
||
* ePerl:: A general Perl-embedding syntax.
|
||
* JSP:: Java code embedded in HTML.
|
||
* RPM:: Shell scripts in RPM Spec Files.
|
||
* Noweb:: Noweb literate programs.
|
||
|
||
Writing Submode Classes
|
||
|
||
* 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.
|
||
|
||
Indices
|
||
|
||
* Concept Index:: Index of MMM Mode Concepts.
|
||
* Function Index:: Index of functions and variables.
|
||
* Keystroke Index:: Index of key bindings in MMM Mode.
|
||
|
||
@end detailmenu
|
||
@end menu
|
||
|
||
@node Overview, Basics, Top, Top
|
||
@comment node-name, next, previous, up
|
||
@chapter Overview of MMM Mode
|
||
@cindex overview of mmm-mode
|
||
@cindex mmm-mode, overview of
|
||
|
||
MMM Mode is a minor mode for Emacs which allows Multiple Major Modes to
|
||
coexist in a single buffer. The name is an abbreviation of `Multiple
|
||
Major Modes'@footnote{The name is derived from @file{mmm.el} for XEmacs
|
||
by Gongquan Chen <chen@@posc.org>, from which MMM Mode was adapted.}. A
|
||
major mode is a customization of Emacs for editing a certain type of
|
||
text, such as code for a specific programming language. @xref{Major
|
||
Modes, , , emacs, The Emacs Manual}, for details.
|
||
|
||
MMM Mode is a general extension to Emacs which is useful whenever one
|
||
file contains text in two or more programming languages, or that
|
||
should be in two or more different modes. For example:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
CGI scripts written in any language, from Perl to PL/SQL, may want to
|
||
output verbatim HTML, and the writer of such scripts may want to use
|
||
Emacs' html-mode or sgml-mode to edit this HTML code, while remaining
|
||
in the appropriate programming language mode for the rest of the
|
||
file. @xref{Here-documents}, for example.
|
||
|
||
@item
|
||
There are now many ``content delivery systems'' which turn the CGI
|
||
script idea around and simply add extra commands to an HTML file,
|
||
often in some programming language, which are interpreted on the
|
||
server. @xref{Mason}, @xref{Embperl}, @xref{ePerl}, @xref{JSP}.
|
||
|
||
@item
|
||
HTML itself can also contain embedded languages such as Javascript and
|
||
CSS styles, for which Emacs has different major modes.
|
||
@xref{Javascript}, and @xref{Embedded CSS}, for example.
|
||
|
||
@item
|
||
The idea of ``literate programming'' requires the same file to contain
|
||
documentation (written as text, html, latex, etc.) and code (in an
|
||
appropriate programming language). @xref{Noweb}, for example.
|
||
|
||
@item
|
||
Emacs allows files of any type to contain `local variables', which can
|
||
include Emacs Lisp code to be evaluated. @xref{File Variables, , ,
|
||
emacs, The Emacs Manual}. It may be easier to edit this code in Emacs
|
||
Lisp mode than in whatever mode is used for the rest of the file.
|
||
@xref{File Variables}.
|
||
|
||
@item
|
||
There are many more possible uses for MMM Mode. RPM spec files can
|
||
contain shell scripts (@pxref{RPM}). Email or newsgroup messages may
|
||
contain sample code. And so on. We encourage you to experiment.
|
||
@end itemize
|
||
|
||
@menu
|
||
* Basic Concepts:: A simple explanation of how it works.
|
||
* Installation:: How to install MMM Mode.
|
||
* Quick Start:: Getting started using MMM Mode quickly.
|
||
@end menu
|
||
|
||
@node Basic Concepts, Installation, Overview, Overview
|
||
@comment node-name, next, previous, up
|
||
@section Basic Concepts
|
||
@cindex dominant major mode
|
||
@cindex major mode, dominant
|
||
@cindex default major mode
|
||
@cindex major mode, default
|
||
@cindex submode regions
|
||
@cindex regions, submode
|
||
@cindex overlays, submode
|
||
@cindex submode overlays
|
||
@cindex mmm-ification
|
||
|
||
The way MMM Mode works is as follows. Each buffer has a @dfn{dominant}
|
||
or @dfn{default} major mode, which is chosen as major modes normally
|
||
are: the user can set it interactively, or it can be chosen
|
||
automatically with `auto-mode-alist' (@pxref{Choosing Modes, , , emacs,
|
||
The Emacs Manual}). Within the file, MMM Mode creates @dfn{submode
|
||
regions} within which other major modes are in effect. While the point
|
||
is in a submode region, the following changes occur:
|
||
|
||
@enumerate
|
||
@item
|
||
The local keymap is that of the submode. This means the key bindings for
|
||
the submode are available, while those of the dominant mode are not.
|
||
@item
|
||
The mode line (@pxref{Mode Line, , , emacs, The Emacs Manual}) changes
|
||
to show which submode region is active. This can be configured; see
|
||
@ref{Mode Line}.
|
||
@item
|
||
The major mode menu, both on the menu bar and the mouse popup, are that
|
||
of the submode.
|
||
@item
|
||
Some local variables of the submode shadow those of the default mode
|
||
(@pxref{Local Variables}). For the user, this serves to help make Emacs
|
||
behave as if the submode were the major mode.
|
||
@item
|
||
The syntax table and indentation are those of the submode.
|
||
@item
|
||
Font-lock (@pxref{Font Lock, , , emacs, The Emacs Manual}) fontifies
|
||
correctly for the submode.
|
||
@item
|
||
The submode regions are highlighted by a background color; see
|
||
@ref{Region Coloring}.
|
||
|
||
@end enumerate
|
||
|
||
The submode regions are represented internally by Emacs Lisp objects
|
||
known as @dfn{overlays}. Some of the above are implemented by overlay
|
||
properties, and others are updated by an MMM Mode function in
|
||
`post-command-hook'. You don't need to know this to use MMM Mode, but it
|
||
may make any error messages you come across more understandable.
|
||
@xref{Overlays, , , elisp, The GNU Emacs Lisp Reference Manual}, for
|
||
more information on overlays.
|
||
|
||
Because overlays are not saved with a file, every time a file is opened,
|
||
they must be created. Creating submode regions is occasionally referred
|
||
to as @dfn{mmm-ification}. (I've never had occasion to pronounce this,
|
||
but if I did I would probably say `mummification'. Like what they did in
|
||
ancient Egypt.) You can mmm-ify a buffer interactively, but most often
|
||
MMM Mode will find and create submode regions automatically based on a
|
||
buffer's file extension, dominant mode, or local variables.
|
||
|
||
|
||
@node Installation, Quick Start, Basic Concepts, Overview
|
||
@comment node-name, next, previous, up
|
||
@section Installing MMM Mode
|
||
|
||
MMM Mode has a standard installation process. See the file INSTALL for
|
||
generic information on this process. To summarize, unpack the archive,
|
||
@command{cd} to the created MMM Mode directory, type @samp{./configure},
|
||
then @samp{make}, then @samp{make install}. If all goes correctly, this
|
||
will compile the MMM Mode elisp files, install them in your local
|
||
site-lisp directory, and install the MMM Mode info file @file{mmm.info}
|
||
in your local info directory.
|
||
|
||
Now you need to configure your Emacs initialization file (usually
|
||
@file{~/.emacs}) to use MMM Mode. First, Emacs has to know where to
|
||
find MMM Mode. In other words, the MMM Mode directory has to be in
|
||
@code{load-path}. This can be done in the parent directory's
|
||
@file{subdirs.el} file, or in the init file with a line such as:
|
||
|
||
@lisp
|
||
(add-to-list 'load-path "/path/to/site-lisp/mmm/")
|
||
@end lisp
|
||
|
||
Once @code{load-path} is configured, MMM Mode must be loaded. You can
|
||
load all of MMM Mode with the line
|
||
|
||
@lisp
|
||
(require 'mmm-mode)
|
||
@end lisp
|
||
|
||
@noindent
|
||
but if you use MMM Mode only rarely, it may not be desirable to load all
|
||
of it at the beginning of every editing session. You can load just
|
||
enough of MMM Mode so it will turn itself on when necessary and load the
|
||
rest of itself, by using instead the line
|
||
|
||
@lisp
|
||
(require 'mmm-auto)
|
||
@end lisp
|
||
|
||
@noindent
|
||
in your initialization file.
|
||
|
||
One more thing you may want to do right now is to set the variable
|
||
@code{mmm-global-mode}. If this variable is @code{nil} (the default),
|
||
MMM Mode will never turn itself on. If it is @code{t}, MMM Mode will
|
||
turn itself on in every buffer. Probably the most useful value for it,
|
||
however, is the symbol @code{maybe} (actually, anything that is not
|
||
@code{nil} and not @code{t}), which causes MMM Mode to turn itself on in
|
||
precisely those buffers where it would be useful. You can do this with
|
||
a line such as:
|
||
|
||
@lisp
|
||
(setq mmm-global-mode 'maybe)
|
||
@end lisp
|
||
|
||
@noindent
|
||
in your initialization file. @xref{Global Mode}, for more detailed
|
||
information.
|
||
|
||
|
||
@node Quick Start, , Installation, Overview
|
||
@comment node-name, next, previous, up
|
||
@section Getting Started Quickly
|
||
|
||
Perhaps the simplest way to create submode regions is to do it
|
||
interactively by specifying a region. First you must turn MMM Mode
|
||
on---say, with @kbd{M-x mmm-mode}---then place point and mark around the
|
||
area you want to make into a submode region, type @kbd{C-c % C-r}, and
|
||
enter the desired major mode. @xref{Interactive}, for more details.
|
||
|
||
A better way to add submode regions is by using submode classes, which
|
||
store a lot of useful information for MMM Mode about how to add and
|
||
manipulate the regions created. @xref{Submode Classes}, for more
|
||
details. There are several sample submode classes that come with MMM
|
||
Mode, which are documented later in this manual. Look through these and
|
||
determine if one of them fits your needs. If so, I suggest reading the
|
||
comments on that mode. Then come back here to find out to use it.
|
||
|
||
To apply a submode class to a buffer interactively, turn MMM Mode on as
|
||
above, then type @kbd{C-c % C-c} and enter the name of the class.
|
||
Submode regions should be added automatically, if there are any regions
|
||
in the buffer appropriate to the submode class.
|
||
|
||
If you want a given file to always use a given submode class, you can
|
||
express this in a file variable: add a line containing the string
|
||
@samp{-*- mmm-classes: @var{class} -*-} at the top of the file.
|
||
@xref{File Variables, , , emacs, The Emacs Manual}, for more information
|
||
and other methods. Now whenever MMM Mode is turned on in that file, it
|
||
will be mmm-ified according to @var{class}. If @code{mmm-global-mode} is
|
||
non-nil, then MMM Mode will turn itself on whenever a file with a
|
||
@code{mmm-classes} local variable is opened. @xref{Global Mode}, for more
|
||
information.
|
||
|
||
If you want a submode class to apply to @emph{all} files in a certain
|
||
major mode or with a certain extension, add a line such as this to your
|
||
initialization file:
|
||
|
||
@lisp
|
||
(mmm-add-mode-ext-class @var{mode} @var{extension} @var{class})
|
||
@end lisp
|
||
|
||
@noindent
|
||
After this call, any file opened whose name matches the regular
|
||
expression @var{extension} @emph{and} whose default mode is @var{mode}
|
||
will be automatically mmm-ified according to @var{class} (assuming
|
||
@code{mmm-global-mode} is non-nil). If one of @var{extension} or
|
||
@var{mode} is @code{nil}, a file need only satisfy the other one to be
|
||
mmm-ified.
|
||
|
||
You can now read the rest of this manual to learn more about how MMM
|
||
Mode works and how to configure it to your preferences. If none of the
|
||
supplied submode classes fit your needs, then you can try to write your
|
||
own. @xref{Writing Classes}, for more information.
|
||
|
||
@node Basics, Customizing, Overview, Top
|
||
@comment node-name, next, previous, up
|
||
@chapter MMM Mode Basics
|
||
|
||
This chapter explains the most important parts of how to use MMM Mode.
|
||
|
||
@menu
|
||
* MMM Minor Mode:: The Emacs minor mode that manages it all.
|
||
* Submode Classes:: What they are and how to use them.
|
||
* Selecting Classes:: How MMM Mode knows what classes to use.
|
||
* Insertion:: Inserting new submode regions automatically.
|
||
* Re-parsing:: Re-scanning for submode regions.
|
||
* Interactive:: Adding submode regions manually.
|
||
* Global Mode:: Turning MMM Mode on automatically.
|
||
@end menu
|
||
|
||
@node MMM Minor Mode, Submode Classes, Basics, Basics
|
||
@comment node-name, next, previous, up
|
||
@section The MMM Minor Mode
|
||
@cindex mode, mmm minor
|
||
@cindex minor mode, mmm
|
||
@cindex mmm minor mode
|
||
|
||
An Emacs minor mode is an optional feature which can be turned on or off
|
||
in a given buffer, independently of the major mode. @xref{Minor Modes, ,
|
||
, emacs, The Emacs Manual}. MMM Mode is implemented as a minor mode
|
||
which manages the submode regions. This minor mode must be turned on in
|
||
a buffer for submode regions to be effective. When activated, the MMM
|
||
Minor mode is denoted by @samp{MMM} in the mode line (@pxref{Mode
|
||
Line}).
|
||
|
||
@menu
|
||
* Enabling MMM Mode:: Turning MMM Mode on and off.
|
||
* MMM Mode Keys:: Default key bindings in MMM Mode.
|
||
@end menu
|
||
|
||
|
||
@node Enabling MMM Mode, MMM Mode Keys, MMM Minor Mode, MMM Minor Mode
|
||
@comment node-name, next, previous, up
|
||
@subsection Enabling MMM Mode
|
||
@cindex mmm mode, turning on
|
||
@cindex mmm mode, turning off
|
||
@cindex turning on mmm mode
|
||
@cindex turning off mmm mode
|
||
@cindex mmm mode, enabling
|
||
@cindex mmm mode, disabling
|
||
@cindex enabling mmm mode
|
||
@cindex disabling mmm mode
|
||
|
||
If @code{mmm-global-mode} is non-@code{nil} (@pxref{Global Mode}),
|
||
then the MMM minor mode will be turned on automatically whenever a file
|
||
with associated submode classes is opened (@pxref{Selecting Classes}).
|
||
It is also turned on by interactive mmm-ification (@pxref{Interactive}),
|
||
although the interactive commands do not have key bindings when it is
|
||
not on and must be invoked via @kbd{M-x}. You can also turn it on (or
|
||
off) manually with @kbd{M-x mmm-mode}, in which case it applies all
|
||
submode classes associated with the buffer. Turning MMM Mode off
|
||
automatically removes all submode regions from the buffer.
|
||
|
||
@deffn Command mmm-mode @var{arg}
|
||
Toggle the state of MMM Mode in the current buffer. If @var{arg} is
|
||
supplied, turn MMM Mode on if and only if @var{arg} is positive.
|
||
@end deffn
|
||
|
||
@defun mmm-mode-on
|
||
Turn MMM Mode on unconditionally in the current buffer.
|
||
@end defun
|
||
|
||
@defun mmm-mode-off
|
||
Turn MMM Mode off unconditionally in the current buffer.
|
||
@end defun
|
||
|
||
@defvar mmm-mode
|
||
This variable represents whether MMM Mode is on in the current buffer.
|
||
Do not set this variable directly; use one of the above functions.
|
||
@end defvar
|
||
|
||
|
||
@node MMM Mode Keys, , Enabling MMM Mode, MMM Minor Mode
|
||
@comment node-name, next, previous, up
|
||
@subsection Key Bindings in MMM Mode
|
||
@cindex mmm mode key bindings
|
||
@cindex key bindings in mmm mode
|
||
@findex mmm-insertion-help
|
||
@kindex C-c % h
|
||
|
||
When MMM Mode is on, it defines a number of key bindings. By default,
|
||
these are bound after the prefix sequence @kbd{C-c %}. Minor mode
|
||
keymaps are supposed to use @kbd{C-c @var{punctuation}} sequences, and I
|
||
find this one to be a good mnemonic because @samp{%} is used by Mason to
|
||
denote special tags. This prefix key can be customized; @ref{Key
|
||
Bindings}.
|
||
|
||
There are two types of key bindings in MMM Mode: @dfn{commands} and
|
||
@dfn{insertions}. Command bindings run MMM Mode interactive functions to
|
||
do things like re-parse the buffer or end the current submode region,
|
||
and are defined statically as normal Emacs key-bindings. Insertion
|
||
bindings insert submode region skeletons with delimiters into the
|
||
buffer, and are defined dynamically, according to which submode classes
|
||
(@pxref{Submode Classes}) are in effect, via a keymap default binding.
|
||
|
||
To distinguish between the two, MMM Mode uses distinct modifier keys for
|
||
each. By default, command bindings use the control key (e.g. @kbd{C-c %
|
||
C-b} re-parses the buffer), and insertion bindings do not (e.g. @kbd{C-c
|
||
% p}, when the Mason class is in effect, inserts a
|
||
@samp{<%perl>...</%perl>} region). This makes the command bindings
|
||
different from in previous versions, however, so the variable
|
||
@code{mmm-use-old-bindings} is provided. If this variable is set to `t'
|
||
before MMM Mode is loaded, the bindings will be reversed: insertion
|
||
bindings will use the control key and command bindings will not.
|
||
|
||
Normally, Emacs gives help on a prefix command if you type @kbd{C-h}
|
||
after that command (e.g. @kbd{C-x C-h} displays all key bindings
|
||
starting with @kbd{C-x}). Because of how insertion bindings are
|
||
implemented dynamically with a default binding, they do not show up when
|
||
you hit @kbd{C-c % C-h}. For this reason, MMM Mode defines the command
|
||
@kbd{C-c % h} which displays a list of all currently valid insertion key
|
||
sequences. If you use the defaults for command and insertion bindings,
|
||
the @kbd{C-h} and @kbd{h} should be mnemonic.
|
||
|
||
In the rest of this manual, I will assume you are using the defaults for
|
||
the mode prefix (@kbd{C-c %}) and the command and insertion modifiers.
|
||
You can customize them, however; @ref{Key Bindings}.
|
||
|
||
|
||
@node Submode Classes, Selecting Classes, MMM Minor Mode, Basics
|
||
@comment node-name, next, previous, up
|
||
@section Understanding Submode Classes
|
||
@cindex submode classes
|
||
@cindex classes, submode
|
||
|
||
A submode class represents a ``type'' of submode region. It specifies
|
||
how to find the regions, what their delimiters look like, what submode
|
||
they should be, how to insert them, and how they behave in other ways.
|
||
It is represented by a symbol, such as @code{mason} or
|
||
@code{eval-elisp}.
|
||
|
||
For example, in the Mason set of classes, there is one class
|
||
representing all @samp{<%...%>} inline Perl regions, and one
|
||
representing regions such as @samp{<%perl>...</%perl>},
|
||
@samp{<%init>...</%init>}, and so on. These are different to Mason, but
|
||
to Emacs they are all just Perl sections, so they are covered by the
|
||
same submode class.
|
||
|
||
But it would be tedious if whenever we wanted to use the Mason classes,
|
||
we had to specify both of these. (Actually, this is a simplification:
|
||
there are some half a dozen Mason submode classes.) So submode classes
|
||
can also ``group'' others together, and we can refer to the @code{mason}
|
||
class and mean all of them.
|
||
|
||
The way a submode class is used is to @dfn{apply} it to a buffer. This
|
||
scans the buffer for regions which should be submode regions according
|
||
to that class, and also remembers the class for later, so that new
|
||
submode regions can be inserted and scanned for later.
|
||
|
||
|
||
@node Selecting Classes, Insertion, Submode Classes, Basics
|
||
@comment node-name, next, previous, up
|
||
@section How MMM Mode selects submode classes
|
||
|
||
Submode classes that apply to a buffer come from three sources:
|
||
mode/extension-associated classes, file-local classes, and interactive
|
||
MMM-ification (@pxref{Interactive}). Whenever MMM Mode is turned on in a
|
||
buffer (@pxref{MMM Minor Mode}, and @ref{Global Mode}), it inspects the
|
||
value of two variables to determine which classes to automatically apply
|
||
to the buffer. This covers the first two sources; the latter is covered
|
||
in a later chapter.
|
||
|
||
@menu
|
||
* File Classes:: Classes for a single file.
|
||
* Mode-Ext Classes:: Classes for a given mode or extension.
|
||
* Global Classes:: Classes for all MMM Mode buffers.
|
||
@end menu
|
||
|
||
|
||
@node File Classes, Mode-Ext Classes, Selecting Classes, Selecting Classes
|
||
@comment node-name, next, previous, up
|
||
@subsection File-Local Submode Classes
|
||
|
||
@defvar mmm-classes
|
||
This variable is always buffer-local when set. Its value should be
|
||
either a single symbol or a list of symbols. Each symbol represents a
|
||
submode class that is applied to the buffer.
|
||
@end defvar
|
||
|
||
@code{mmm-classes} is usually set in a file local variables list.
|
||
@xref{File Variables, , , emacs, The Emacs Manual}. The easiest way to
|
||
do this is for the first line of the file to contain the string
|
||
@samp{-*- mmm-classes: @var{classes} -*-}, where @var{classes} is the
|
||
desired value of @code{mmm-classes} for the file in question. It can
|
||
also be done with a local variables list at the end of the file.
|
||
|
||
|
||
@node Mode-Ext Classes, Global Classes, File Classes, Selecting Classes
|
||
@comment node-name, next, previous, up
|
||
@subsection Submode Classes Associated with Modes and Extensions
|
||
|
||
@defopt mmm-mode-ext-classes-alist
|
||
This global variable associates certain submode classes with major modes
|
||
and/or file extensions. Its value is a list of elements of the form
|
||
@code{(@var{mode} @var{ext} @var{class})}. Any buffer whose major mode
|
||
is @var{mode} (a symbol) @emph{and} whose file name matches @var{ext} (a
|
||
regular expression) will automatically have the submode class
|
||
@var{class} applied to it.
|
||
|
||
If @var{mode} is @code{nil}, then only @var{ext} is considered to
|
||
determine if a buffer fits the criteria, and vice versa. Thus if both
|
||
@var{mode} and @var{ext} are nil, then @var{class} is applied to
|
||
@emph{all} buffers in which MMM Mode is on. Note that @var{ext} can be
|
||
any regular expression, although its name indicates that it most often
|
||
refers to the file extension.
|
||
|
||
If @var{class} is the symbol @code{t}, then no submode class is actually
|
||
applied for this association. However, if @code{mmm-global-mode} is
|
||
non-@code{nil} and non-@code{t}, MMM Mode will be turned on in matching
|
||
buffers even if there are no actual submode classes being applied.
|
||
@xref{Global Mode}.
|
||
@end defopt
|
||
|
||
@defun mmm-add-mode-ext-class @var{mode} @var{ext} @var{class}
|
||
This function adds an element to @code{mmm-mode-ext-classes-alist},
|
||
associating the submode class @var{class} with the major mode @var{mode}
|
||
and extension @var{ext}.
|
||
|
||
Older versions of MMM Mode required this function to be used to control
|
||
the value of @code{mmm-mode-ext-classes-alist}, rather than setting it
|
||
directly. In this version it is provided purely for convenience and
|
||
backward compatibility.
|
||
@end defun
|
||
|
||
|
||
@node Global Classes, , Mode-Ext Classes, Selecting Classes
|
||
@comment node-name, next, previous, up
|
||
@subsection Globally Applied Classes and the Universal Class
|
||
|
||
In addition to file-local and mode-ext-associated submode classes, MMM
|
||
Mode also allows you to specify that certain submode classes apply to
|
||
@emph{all} buffers in which MMM Mode is enabled.
|
||
|
||
@defopt mmm-global-classes
|
||
This variable's value should be a list of submode classes that apply to
|
||
all buffers with MMM Mode on. It can be overriden in a file local
|
||
variables list, such as to disable global class for a specific file.
|
||
Its default value is @code{(universal)}.
|
||
@end defopt
|
||
|
||
The default global class is the ``universal class'', which is defined in
|
||
the file @file{mmm-univ.el} (loaded automatically), and allows the
|
||
author of text to specify that a certain section of it be in a specific
|
||
major mode. Thus, for example, when writing an email message that
|
||
includes sample code, the author can allow readers of the message (who
|
||
use emacs and MMM) to view the code in the appropriate major mode. The
|
||
syntax used is @samp{@{%@var{mode}%@} ... @{%/@var{mode}%@}}, where
|
||
@var{mode} should be the name of the major mode, with or without the
|
||
customary @samp{-mode} suffix: for example, both @samp{cperl} and
|
||
@samp{cperl-mode} are acceptable.
|
||
|
||
The universal class also defines an insertion key, @samp{/}, which
|
||
prompts for the submode to use. @xref{Insertion}. The universal class
|
||
is most useful when @code{mmm-global-mode} is set to @code{t};
|
||
@ref{Global Mode}.
|
||
|
||
|
||
@node Insertion, Re-parsing, Selecting Classes, Basics
|
||
@comment node-name, next, previous, up
|
||
@section Inserting new submode regions
|
||
|
||
So much for noticing submode regions already present when you open a
|
||
file. When editing a file with MMM Mode on, you will often want to add a
|
||
new submode region. MMM Mode provides several facilities to help you.
|
||
The simplest is to just hit a few keys and have the region and its
|
||
delimiters inserted for you.
|
||
|
||
Each submode class can define an association of keystrokes with
|
||
``skeletons'' to insert a submode region. If there are several submode
|
||
classes enabled in a buffer, it is conceivable that the keys they use
|
||
for insertion might conflict, but unlikely as most buffers will not use
|
||
more than one or two submode classes groups.
|
||
|
||
As an example of how insertion works, consider the Mason classes. In a
|
||
buffer with MMM Mode enabled and Mason associated, the key sequence
|
||
@kbd{C-c % p} inserts the following perl section (the semicolon is to
|
||
prevent CPerl Mode from getting confused---@pxref{Mason}):
|
||
|
||
@example
|
||
<%perl>-<-;
|
||
-!-
|
||
->-</%perl>
|
||
@end example
|
||
|
||
In this schematic representation, the string @samp{-!-} represents the
|
||
position of point (the cursor), @samp{-<-} represents the beginning of
|
||
the submode region, and @samp{->-} its end.
|
||
|
||
All insertion keys come after the MMM Mode prefix keys (by default
|
||
@kbd{C-c %}; @pxref{Key Bindings}) and are by default single characters
|
||
such as @kbd{p}, @kbd{%}, and @kbd{i}. To avoid confusion, all the MMM
|
||
Mode commands are bound by default to control characters (after the same
|
||
prefix keys), such as @kbd{C-b}, @kbd{C-%} and @kbd{C-r}. This is a
|
||
change from earlier versions of MMM Mode, and can be customized; see
|
||
@ref{Key Bindings}.
|
||
|
||
To find out what insertion keys are available, consult the documentation
|
||
for the submode class you are using. If it is one of the classes
|
||
supplied with MMM Mode, you can find it in this Info file.
|
||
|
||
Because insertion keys are implemented with a ``default binding'' for
|
||
flexibility, they do not show up in the output of @kbd{C-h m} and cannot
|
||
be found with @kbd{C-h k}. For this reason, MMM Mode supplies the
|
||
command @kbd{C-c % h} (@code{mmm-insertion-help} to view the available
|
||
insertion keys.
|
||
|
||
|
||
@node Re-parsing, Interactive, Insertion, Basics
|
||
@comment node-name, next, previous, up
|
||
@section Re-Parsing Submode Regions
|
||
@cindex re-parsing submode regions
|
||
@cindex parsing submode regions
|
||
@cindex submode regions, re-parsing
|
||
@cindex regions, submode, re-parsing
|
||
@cindex submode regions, clearing
|
||
@cindex clearing submode regions
|
||
@cindex regions, submode, clearing
|
||
@kindex C-c % C-b
|
||
@kindex C-c % C-g
|
||
@kindex C-c % C-%
|
||
@kindex C-c % C-5
|
||
@kindex C-c % C-k
|
||
|
||
Describe @code{mmm-parse-buffer}, @code{mmm-parse-region},
|
||
@code{mmm-parse-block}, and @code{mmm-clear-current-region}.
|
||
|
||
@node Interactive, Global Mode, Re-parsing, Basics
|
||
@comment node-name, next, previous, up
|
||
@section Interactive MMM-ification Functions
|
||
@cindex interactive mmm-ification
|
||
@cindex mmm-ification, interactive
|
||
@cindex mmm-ification by region
|
||
@cindex mmm-ification by regexp
|
||
@cindex mmm-ification by class
|
||
@cindex region, mmm-ification by
|
||
@cindex regexp, mmm-ification by
|
||
@cindex class, mmm-ification by
|
||
@kindex C-c % C-r
|
||
@kindex C-c % C-c
|
||
@kindex C-c % C-x
|
||
@cindex mmm-ification, interactive history
|
||
@cindex history of interactive mmm-ification
|
||
@cindex interactive mmm-ification, history of
|
||
|
||
There are several commands you can use to create submode regions
|
||
interactively, rather than by applying a submode class to a buffer.
|
||
These commands (in particular, @code{mmm-ify-region}), can be useful
|
||
when editing a file or email message containing a snippet of code in
|
||
some other language. Also see @ref{Global Classes}, for an alternate
|
||
approach to the same problem.
|
||
|
||
@table @kbd
|
||
@item C-c % C-r
|
||
Creates a submode region between point and mark. Prompts for the submode
|
||
to use, which must be a valid Emacs major mode name, such as
|
||
@code{emacs-lisp-mode} or @code{cperl-mode}. Adds markers to the
|
||
interactive history. (@code{mmm-ify-region})
|
||
|
||
@item C-c % C-c
|
||
Applies an already-defined submode class to the buffer, which it prompts
|
||
for. Adds this class to the interactive history.
|
||
(@code{mmm-ify-by-class})
|
||
|
||
@item C-c % C-x
|
||
Scans the buffer for submode regions (prompts for the submode) using
|
||
front and back regular expressions that it also prompts for. Briefly, it
|
||
starts at the beginning of the buffer and searches for the front regexp.
|
||
If it finds a match, it searches for the back regexp. If it finds a
|
||
match for that as well, it makes a submode region between the two
|
||
matches and continues searching until no more matches are found. Adds
|
||
the regexps to the interactive history. (@code{mmm-ify-by-regexp})
|
||
|
||
@end table
|
||
|
||
These commands are also useful when designing a new submode class
|
||
(@pxref{Submode Classes}). Working with the regexps interactively can
|
||
make it easier to debug and tune the class before starting to use it on
|
||
automatic. All these commands also add to value of the following
|
||
variable.
|
||
|
||
@defvar mmm-interactive-history
|
||
Stores a history of all interactive mmm-ification that has been
|
||
performed in the current buffer. This way, for example, the re-parsing
|
||
functions (@pxref{Re-parsing}) will respect interactively added regions,
|
||
and the insertion keys for classes that were added interactively are
|
||
available.
|
||
@end defvar
|
||
|
||
If for any reason you want to ``wipe the slate clean'', this command
|
||
should help you. By default, it has no key binding, so you must invoke
|
||
it with @kbd{M-x mmm-clear-history @key{RET}}.
|
||
|
||
@deffn Command mmm-clear-history
|
||
Clears all history of interactive mmm-ification in the current buffer.
|
||
This command does not affect existing submode regions; to remove them,
|
||
you may want to re-parse the buffer with @kbd{C-c % C-b}
|
||
(@code{mmm-parse-buffer}).
|
||
@end deffn
|
||
|
||
|
||
@node Global Mode, , Interactive, Basics
|
||
@comment node-name, next, previous, up
|
||
@section MMM Global Mode
|
||
@cindex mode, mmm global
|
||
@cindex global mmm mode
|
||
@cindex mmm global mode
|
||
@vindex mmm-never-modes
|
||
|
||
When a file has associated submode classes (@pxref{Selecting Classes}),
|
||
you may want MMM Mode to turn itself on and parse that file for submode
|
||
regions automatically whenever it is opened in an Emacs buffer. The
|
||
value of the following variable controls when MMM Mode turns itself on
|
||
automatically.
|
||
|
||
@defopt mmm-global-mode
|
||
Do not be misled by the fact that this variable's name ends in
|
||
@samp{-mode}: it is not a simple on/off switch. There are three possible
|
||
(meanings of) values for it: @code{t}, @code{nil}, and anything else.
|
||
|
||
When this variable is @code{nil}, MMM Mode is never enabled
|
||
automatically. If it is enabled manually, such as by typing @kbd{M-x
|
||
mmm-mode}, any submode classes associated with the buffer will still be
|
||
used, however.
|
||
|
||
When this variable is @code{t}, MMM Mode is enabled automatically in
|
||
@emph{all} buffers, including those not visiting files, except those
|
||
whose major mode is an element of @code{mmm-never-modes}. The default
|
||
value of this variable contains modes such as @code{help-mode} and
|
||
@code{dired-mode} in which most users would never want MMM Mode, and
|
||
in which MMM might cause problems.
|
||
|
||
When this variable is neither @code{nil} nor @code{t}, MMM Mode is
|
||
enabled automatically in all buffers that would have associated submode
|
||
classes; i.e. only if there would be something for it to do. The value
|
||
of @code{mmm-never-modes} is still respected, however. Note that this
|
||
can include buffers not visiting files, if that buffer's major mode is
|
||
present in @code{mmm-mode-ext-classes-alist} with a @code{nil} value for
|
||
@var{ext} (@pxref{Mode-Ext Classes}). Submode class values of @code{t}
|
||
in @code{mmm-mode-ext-classes-alist} cause MMM Mode to be enabled in
|
||
matching buffers, but supply no submode classes to be applied.
|
||
@end defopt
|
||
|
||
@menu
|
||
* Major Mode Hook:: Using MMM's Major Mode Hook
|
||
@end menu
|
||
|
||
|
||
@node Major Mode Hook, , Global Mode, Global Mode
|
||
@comment node-name, next, previous, up
|
||
@subsection The Major Mode Hook
|
||
@cindex hook, major mode
|
||
@cindex major mode hook
|
||
@vindex mmm-major-mode-hook
|
||
|
||
This section is intended for users who understand Emacs Lisp and want to
|
||
know how MMM Global Mode is implemented, and perhaps use the same
|
||
technique. In fact, MMM Mode exports a hook variable that you can use
|
||
easily, without understanding any of the details---see below.
|
||
|
||
In order to enable itself in @emph{all} buffers, however, MMM Mode has
|
||
to hook itself into all major modes. Global Font Lock Mode from the
|
||
standard Emacs distribution (@pxref{Font Lock, , , emacs, The Emacs
|
||
Manual}) has a similar problem, and solves it by adding a function to
|
||
@code{change-major-mode-hook}, which is run by
|
||
@code{kill-all-local-variables}, which is run in turn by all major mode
|
||
functions at the @emph{beginning}. This function stores a list of which
|
||
buffers need fontification. It then adds a different function to
|
||
@code{post-command-hook}, which checks if the current buffer needs
|
||
fontification, and if so performs it. MMM Global Mode uses the same
|
||
technique.
|
||
|
||
In the interests of generality, and for your use, the function that MMM
|
||
Mode runs in @code{post-command-hook} (@code{mmm-run-major-mode-hook})
|
||
is not specific to MMM Mode, but rather runs the hook variable
|
||
@code{mmm-major-mode-hook}, which by default contains a function
|
||
(@code{mmm-mode-on-maybe}) which possibly turns MMM Mode on, depending
|
||
on the value of @code{mmm-global-mode}. Thus, to run another function
|
||
in all major modes, all you need to do is add it to this hook. For
|
||
example, the following line in an initialization file will turn on Auto
|
||
Fill Mode (@pxref{Auto Fill, , , emacs, The Emacs Manual}) in all
|
||
buffers:
|
||
|
||
@lisp
|
||
(add-hook 'mmm-major-mode-hook 'turn-on-auto-fill)
|
||
@end lisp
|
||
|
||
@node Customizing, Supplied Classes, Basics, Top
|
||
@comment node-name, next, previous, up
|
||
@chapter Customizing MMM Mode
|
||
|
||
This chapter explains how to customize the appearance and functioning of
|
||
MMM Mode however you want.
|
||
|
||
@menu
|
||
* Region Coloring:: Changing or removing background colors.
|
||
* Preferred Modes:: Choosing which major modes to use.
|
||
* Mode Line:: What is displayed in the mode line.
|
||
* Key Bindings:: Customizing the MMM Mode key bindings.
|
||
* 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.
|
||
@end menu
|
||
|
||
@node Region Coloring, Preferred Modes, Customizing, Customizing
|
||
@comment node-name, next, previous, up
|
||
@section Customizing Region Coloring
|
||
@cindex faces, submode
|
||
@cindex submode faces
|
||
@cindex customizing submode faces
|
||
@cindex default submode face
|
||
|
||
By default, MMM Mode highlights all submode regions with a background
|
||
color. There are three levels of this decoration, controlled by the
|
||
following variable:
|
||
|
||
@defopt mmm-submode-decoration-level
|
||
This variable controls the level of coloring of submode regions. It
|
||
should be one of the integers 0, 1, or 2, representing (respectively)
|
||
none, low, and high coloring.
|
||
@end defopt
|
||
|
||
No coloring means exactly that. Submode regions have the same
|
||
background as the rest of the text. This produces the minimal
|
||
interference with font-lock coloration. In particular, if you want to
|
||
use background colors for font-lock, this may be a good idea, because
|
||
the submode highlight, if present, overrides any font-lock background
|
||
coloring.
|
||
|
||
Low coloring uses the same background color for all submode regions.
|
||
This color is specified with the face @code{mmm-default-submode-face}
|
||
(@pxref{Faces, , , emacs, The Emacs Manual}) which can be customized,
|
||
either through the Emacs ``customize'' interface or using direct Lisp
|
||
commands such as @code{set-face-background}. Of course, other aspects
|
||
of the face can also be set, such as the foreground color, bold,
|
||
underline, etc. These are more likely to conflict with font-lock,
|
||
however, so only a background color is recommended.
|
||
|
||
High coloring uses multiple background colors, depending on the function
|
||
of the submode region. The recognized functions and their meanings are
|
||
as follows:
|
||
|
||
@table @samp
|
||
@item init
|
||
Code that is executed at the beginning of (something), as initialization
|
||
of some sort.
|
||
|
||
@item cleanup
|
||
Code that is executed at the end of (something), as some sort of clean
|
||
up facility.
|
||
|
||
@item declaration
|
||
Code that provides declarations of some sort, perhaps global or local
|
||
arguments, variables, or methods.
|
||
|
||
@item comment
|
||
Text that is not executed as code, but instead serves to document the
|
||
code around it. Submode regions of this function often use a mode such
|
||
as Text Mode rather than a programming language mode.
|
||
|
||
@item output
|
||
An expression that is evaluated and its value interpolated into the
|
||
output produced.
|
||
|
||
@item code
|
||
Executed code not falling under any other category.
|
||
|
||
@item special
|
||
Submode regions not falling under any other category, such as component
|
||
calls.
|
||
|
||
@end table
|
||
|
||
The different background colors are provided by the faces
|
||
@code{mmm-@var{function}-submode-face}, which can be customized in the
|
||
same way as @code{mmm-default-submode-face}.
|
||
|
||
|
||
@node Preferred Modes, Mode Line, Region Coloring, Customizing
|
||
@comment node-name, next, previous, up
|
||
@section Preferred Major Modes
|
||
|
||
Certain of the supplied submode classes know only the language that
|
||
certain sections are written in, but not what major mode you prefer to
|
||
use to edit such code. For example, many people prefer CPerl mode over
|
||
Perl mode; you may have a special mode for Javascript or just use C++
|
||
mode. This variable allows you to tell submodes such as Mason
|
||
(@pxref{Mason}) and Embedded Javascript (@pxref{Javascript}) what major
|
||
mode to use for the submodes:
|
||
|
||
@defopt mmm-major-mode-preferences
|
||
The elements of this list are cons cells of the form
|
||
@code{(@var{language} . @var{mode})}. @var{language} should be a symbol
|
||
such as @code{perl}, @code{html-js}, or @code{java}, while @var{mode}
|
||
should be the name of a major mode such as @code{perl-mode},
|
||
@code{cperl-mode}, @code{javascript-mode}, or @code{c++-mode}.
|
||
|
||
You probably won't have to set this variable at all; MMM tries to make
|
||
intelligent guesses about what modes you prefer. For example, if a
|
||
function called @code{javascript-mode} exists, it is chosen, otherwise
|
||
@code{c++-mode} is used. Similarly for @code{jde-mode} and
|
||
@code{java-mode}.
|
||
@end defopt
|
||
|
||
If you do need to change the defaults, you may find the following
|
||
function convenient.
|
||
|
||
@defun mmm-set-major-mode-preferences @var{language} @var{mode} &optional @var{default}
|
||
Set the preferred major mode for LANGUAGE to MODE. If there is already
|
||
a mode specified for LANGUAGE, and DEFAULT is nil or unsupplied, then it
|
||
is changed. If DEFAULT is non-nil, then any existing mode is unchanged.
|
||
This is used by packages to ensure that some mode is present, but not
|
||
override any user-specified mode. If you are not writing a submode
|
||
class, you should ignore the third argument.
|
||
@end defun
|
||
|
||
Thus, for example, to use @code{my-java-mode} for Java code, you would
|
||
use the following line:
|
||
|
||
@lisp
|
||
(mmm-set-major-mode-preferences 'java 'my-java-mode)
|
||
@end lisp
|
||
|
||
|
||
@node Mode Line, Key Bindings, Preferred Modes, Customizing
|
||
@comment node-name, next, previous, up
|
||
@section Customizing the Mode Line Display
|
||
|
||
By default, when in a submode region, MMM Mode changes the section of
|
||
the mode line (@pxref{Mode Line, , , emacs, The Emacs Manual}) that
|
||
normally displays the major mode name---for example, @samp{HTML}---to
|
||
instead show both the dominant major mode and the currently active
|
||
submode---for example, @samp{HTML[CPerl]}. You can change this format,
|
||
however.
|
||
|
||
@defopt mmm-submode-mode-line-format
|
||
The value of this variable should be a string containing one or both of
|
||
the escape sequences @samp{~M} and @samp{~m}. The string displayed in
|
||
the major mode section of the mode line when in a submode is obtained by
|
||
replacing all occurrences of @samp{~M} with the dominant major mode name
|
||
and @samp{~m} with the currently active submode name. For example, to
|
||
display only the currently active submode, set this variable to
|
||
@samp{~m}. The default value is @samp{~M[~m]}.
|
||
@end defopt
|
||
|
||
The MMM minor mode also normally displays the string @samp{MMM} in the
|
||
minor mode section of the mode line to indicate when it is active. You
|
||
can customize or disable this as well.
|
||
|
||
@defopt mmm-mode-string
|
||
This string is displayed in the minor mode section of the mode line when
|
||
the MMM minor mode is active. If nonempty, it should begin with a space
|
||
to separate the MMM indicator from that of other minor modes. To
|
||
eliminate the indicator entirely, set this variable to the empty string.
|
||
@end defopt
|
||
|
||
|
||
@node Key Bindings, Local Variables, Mode Line, Customizing
|
||
@comment node-name, next, previous, up
|
||
@section 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.
|
||
|
||
@defopt 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.
|
||
@end defopt
|
||
|
||
@defopt 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
|
||
@kbd{C-c % C-p}. This variable should be set before MMM Mode is loaded
|
||
to have an effect.
|
||
@end 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
|
||
@code{mmm-insert-modifiers}, so if you prefer you can set these
|
||
variables instead. They should each be a list of key modifiers, such as
|
||
@code{(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, Customizing
|
||
@comment node-name, next, previous, up
|
||
@section 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.
|
||
|
||
@defvar 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
|
||
@code{region}. 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''.
|
||
@end 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, Customizing
|
||
@comment node-name, next, previous, up
|
||
@section 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.
|
||
|
||
@defun mmm-set-class-parameter @var{class} @var{param} @var{value}
|
||
Set the value of the keyword parameter @var{param} of the submode class
|
||
@var{class} 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.
|
||
@end defun
|
||
|
||
@defun mmm-get-class-parameter @var{class} @var{param}
|
||
Get the value of the keyword parameter @var{param} for the submode class
|
||
@var{class}. Returns @code{nil} if there is no such parameter.
|
||
@end defun
|
||
|
||
|
||
|
||
@node Hooks, , Changing Classes, Customizing
|
||
@comment node-name, next, previous, up
|
||
@section Hooks Provided by MMM Mode
|
||
|
||
MMM Mode defines several hook variables (@pxref{Hooks, , , emacs, The
|
||
Emacs Manual}) which are run at different times. The most often used is
|
||
@code{mmm-major-mode-hook} which is described in @ref{Major Mode Hook},
|
||
but there are a couple others.
|
||
|
||
@defvar mmm-mode-hook
|
||
This normal hook is run whenever MMM Mode is enabled in a buffer.
|
||
@end defvar
|
||
|
||
@defvar mmm-@var{major-mode}-hook
|
||
This is actually a whole set of hook variables, a different one for
|
||
every major mode. Whenever MMM Mode is enabled in a buffer, the
|
||
corresponding hook variable for the dominant major mode is run.
|
||
@end defvar
|
||
|
||
@defvar mmm-@var{submode}-submode-hook
|
||
Again, this is a set of one hook variable per major mode. These hooks
|
||
are run whenever a submode region of the corresponding major mode is
|
||
created in any buffer, with point at the start of the new submode
|
||
region.
|
||
@end defvar
|
||
|
||
@defvar mmm-@var{class}-class-hook
|
||
This is a set of one hook variable per submode class. These hooks are
|
||
run when a submode class is first applied to a given buffer.
|
||
@end defvar
|
||
|
||
Submode classes also have a @code{:creation-hook} parameter which should
|
||
be a function to run whenever a submode region is created with that
|
||
class, with point at the beginning of the submode region. This can be
|
||
set for supplied submode classes with @code{mmm-set-class-parameter};
|
||
@ref{Changing Classes}.
|
||
|
||
|
||
@node Supplied Classes, Writing Classes, Customizing, Top
|
||
@comment node-name, next, previous, up
|
||
@chapter Supplied Submode Classes
|
||
|
||
This chapter describes the submode classes that are supplied with MMM
|
||
Mode.
|
||
|
||
@menu
|
||
* Mason:: Mason server-side Perl in HTML.
|
||
* File Variables:: Elisp code in File Variables.
|
||
* Here-documents:: Code in shell and Perl here-documents.
|
||
* Javascript:: Javascript embedded in HTML.
|
||
* Embedded CSS:: CSS Styles embedded in HTML.
|
||
* Embperl:: Another syntax for Perl in HTML.
|
||
* ePerl:: A general Perl-embedding syntax.
|
||
* JSP:: Java code embedded in HTML.
|
||
* RPM:: Shell scripts in RPM Spec Files.
|
||
* Noweb:: Noweb literate programs.
|
||
@end menu
|
||
|
||
@node Mason, File Variables, Supplied Classes, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section Mason: Perl in HTML
|
||
|
||
Mason is a syntax to embed Perl code in HTML and other documents. See
|
||
@uref{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 @value{MASON_VERSION}. There are
|
||
insertion keys for most of the available syntax; use
|
||
@code{mmm-insertion-help} (@kbd{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.
|
||
@xref{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; @ref{Choosing Modes, , , emacs, The Emacs Manual}. This also goes
|
||
for ``special'' Mason files such as autohandlers and dhandlers.
|
||
|
||
The Perl mode used is controlled by the user: @xref{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.
|
||
|
||
@example
|
||
<%perl>;
|
||
print $var;
|
||
</%perl>
|
||
@end example
|
||
|
||
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 @file{.emacs} file should suffice to turn PSGML off
|
||
and cause emacs to use a simpler HTML mode:
|
||
|
||
@lisp
|
||
(autoload 'html-mode "sgml-mode" "HTML Mode" t)
|
||
@end lisp
|
||
|
||
Earlier versions of PSGML may require instead the following fix:
|
||
|
||
@lisp
|
||
(delete '("\\.html$" . sgml-html-mode) auto-mode-alist)
|
||
(delete '("\\.shtml$" . sgml-html-mode) auto-mode-alist)
|
||
@end lisp
|
||
|
||
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 @code{html-mode} in the suggested code with
|
||
@code{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 @code{hm--html-mode}, replace @code{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
|
||
|
||
@example
|
||
<body>
|
||
<% $m->call_next %>
|
||
</body>
|
||
@end example
|
||
|
||
in which case the actual components contain no doctype declaration,
|
||
@code{<html>}, @code{<head>}, or @code{<body>}, confusing PSGML. One
|
||
solution I've found is to use the variable @code{sgml-parent-document}
|
||
in such incomplete components; try, for example, these lines at the end
|
||
of a component.
|
||
|
||
@example
|
||
%# Local Variables:
|
||
%# sgml-parent-document: ("autohandler" "body" nil ("body"))
|
||
%# sgml-doctype: "/top/level/autohandler"
|
||
%# End:
|
||
@end example
|
||
|
||
This tells PSGML that the current file is a sub-document of the file
|
||
@file{autohandler} and is included inside a @code{<body>} tag, thus
|
||
alleviating its confusion.
|
||
|
||
|
||
@node File Variables, Here-documents, Mason, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section 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. @xref{File
|
||
Variables, , , emacs, The Emacs Manual}. Since file variables values
|
||
are Elisp objects (and with the @code{eval} special ``variable'', they
|
||
are forms to be evaluated), one might want to edit them in
|
||
@code{emacs-lisp-mode}. The submode class @code{file-variables} allows
|
||
this, and is suitable for turning on in a given file with
|
||
@code{mmm-classes}, or in all files with @code{mmm-global-classes}.
|
||
|
||
|
||
@node Here-documents, Javascript, File Variables, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section 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:
|
||
|
||
@example
|
||
print <<END_HTML;
|
||
<html>
|
||
<head>
|
||
<title>Test Page</title>
|
||
</head>
|
||
<body>
|
||
END_HTML
|
||
@end example
|
||
|
||
The @code{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 @code{html-mode}, noticing the string
|
||
@samp{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.
|
||
|
||
@defopt 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{("CODE" . cc-mode)}, then any here-document whose name contains
|
||
the string @samp{CODE} will be put in @code{cc-mode}. The value of this
|
||
variable overrides any guessing that the @code{here-doc} submode class
|
||
would do otherwise.
|
||
@end defopt
|
||
|
||
|
||
@node Javascript, Embedded CSS, Here-documents, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section Javascript in HTML
|
||
|
||
The submode class @code{html-js} allows for embedding Javascript code in
|
||
HTML documents. It recognizes both this syntax:
|
||
|
||
@example
|
||
<script language="Javascript">
|
||
function foo(...) @{
|
||
...
|
||
@}
|
||
</script>
|
||
@end example
|
||
|
||
and this syntax:
|
||
|
||
@example
|
||
<input type="button" onClick="validate();">
|
||
@end example
|
||
|
||
The mode used for Javascript regions is controlled by the user;
|
||
@xref{Preferred Modes}.
|
||
|
||
|
||
@node Embedded CSS, Embperl, Javascript, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section CSS embedded in HTML
|
||
|
||
CSS (Cascading Style Sheets) can also be embedded in HTML. The
|
||
@code{embedded-css} submode class recognizes this syntax:
|
||
|
||
@example
|
||
<style>
|
||
h1 @{
|
||
...
|
||
@}
|
||
</style>
|
||
@end example
|
||
|
||
It uses @code{css-mode} if present, @code{c++-mode} otherwise. This can
|
||
be customized: @xref{Preferred Modes}.
|
||
|
||
|
||
@node Embperl, ePerl, Embedded CSS, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section Embperl: More Perl in HTML
|
||
|
||
Embperl is another syntax for embedding Perl in HTML. See
|
||
@uref{http://perl.apache.org/embperl} for more information. The
|
||
@code{embperl} submode class recognizes most if not all of the Embperl
|
||
embedding syntax. Its Perl mode is also controllable by the user;
|
||
@xref{Preferred Modes}.
|
||
|
||
|
||
@node ePerl, JSP, Embperl, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section ePerl: General Perl Embedding
|
||
|
||
Yet another syntax for embedding Perl is called ePerl. See
|
||
@uref{http://www.engelschall.com/sw/eperl/} for more information. The
|
||
@code{eperl} submode class handles this syntax, using the Perl mode
|
||
specified by the user; @xref{Preferred Modes}.
|
||
|
||
|
||
@node JSP, RPM, ePerl, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section JSP: Java Embedded in HTML
|
||
|
||
JSP (Java Server Pages) is a syntax for embedding Java code in HTML.
|
||
The submode class @code{jsp} handles this syntax, using a Java mode
|
||
specified by the user; @xref{Preferred Modes}. The default is
|
||
@code{jde-mode} if present, otherwise @code{java-mode}.
|
||
|
||
|
||
@node RPM, Noweb, JSP, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section RPM Spec Files
|
||
|
||
@file{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
|
||
@file{rpm-spec-mode.el} by Stig Bj<42>rlykke <stigb@@tihlde.hist.no> and
|
||
Steve Sanbeg <sanbeg@@dset.com>
|
||
(@uref{http://www.xemacs.org/~stigb/rpm-spec-mode.el}).
|
||
|
||
Suggested setup code:
|
||
|
||
@lisp
|
||
(add-to-list 'mmm-mode-ext-classes-alist
|
||
'(rpm-spec-mode "\\.spec\\'" rpm-sh))
|
||
@end lisp
|
||
|
||
Thanks to Marcus Harnisch <Marcus.Harnisch@@gmx.net> for contributing
|
||
this submode class.
|
||
|
||
@node Noweb, , RPM, Supplied Classes
|
||
@comment node-name, next, previous, up
|
||
@section Noweb literate programming
|
||
|
||
@file{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 @var{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.
|
||
|
||
@verbatim
|
||
% -*- 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...
|
||
@
|
||
|
||
@end verbatim
|
||
|
||
The quoted code chunks inside documentation chunks are given the mode
|
||
found in the variable @var{mmm-noweb-quote-mode}, if set, or the value
|
||
in @var{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:
|
||
@lisp
|
||
(mmm-add-mode-ext-class 'latex-mode "\\.nw\\'" 'noweb)
|
||
(add-to-list 'auto-mode-alist '("\\.nw\\'" . latex-mode))
|
||
@end lisp
|
||
|
||
In mmm-noweb buffers, each differently-named code chunk has a
|
||
different @code{: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
|
||
(@code{latex-mode, , emacs}) region, pressing @kbd{C-c % C-q} will mark all
|
||
submode regions with word syntax (@code{mmm-word-other-regions}), fill
|
||
the current paragraph (@code{(fill-paragraph justify)}), and remove the
|
||
syntax markings (@code{mmm-undo-syntax-other-regions}).
|
||
|
||
Thanks to Joe Kelsey <joe@@zircon.seattle.wa.us> for contributing this
|
||
class.
|
||
|
||
|
||
@node Writing Classes, Indices, Supplied Classes, Top
|
||
@comment node-name, next, previous, up
|
||
@chapter 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.
|
||
@end menu
|
||
|
||
@node Basic Classes, Paired Delimiters, Writing Classes, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section Writing Basic Submode Classes
|
||
@cindex simple submode classes
|
||
@cindex submode classes, simple
|
||
|
||
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 @code{mmm-classes-alist}.
|
||
Each element of this list represents a single submode class. For
|
||
convenience, the function @code{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 @code{mason} or
|
||
@code{html-js}---followed by pairs of keywords and arguments called a
|
||
@dfn{class specifier}. For example, consider the specifier for the
|
||
submode class @code{embedded-css}:
|
||
|
||
@lisp
|
||
(mmm-add-classes
|
||
'((embedded-css
|
||
:submode css
|
||
:face mmm-declaration-submode-face
|
||
:front "<style[^>]*>"
|
||
:back "</style>")))
|
||
@end lisp
|
||
|
||
The name of the submode is @code{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 @code{:submode} and @code{:front}, and
|
||
arguments, such as @code{css} and @code{"<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 @code{:submode}, @code{:front},
|
||
and @code{:back}. The argument following @code{:submode} names the
|
||
major mode to use in submode regions. It can be either a symbol naming
|
||
a major mode, such as @code{text-mode} or @code{c++-mode}, or a symbol
|
||
to look up in @code{mmm-major-mode-preferences} (@pxref{Preferred
|
||
Modes}) such as @code{css}, as in this case.
|
||
|
||
The arguments following @code{:front} and @code{:back} are regular
|
||
expressions (@pxref{Regexps, , , emacs, The Emacs Manual}) that should
|
||
match the delimiter strings which begin and end the submode regions. In
|
||
our example, CSS regions begin with a @samp{<style>} tag, possibly with
|
||
parameters, and end with a @samp{</style>} tag.
|
||
|
||
The argument following @code{:face} specifies the face (background
|
||
color) to use when @code{mmm-submode-decoration-level} is 2 (high
|
||
coloring). @xref{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.
|
||
|
||
|
||
@node Paired Delimiters, Region Placement, Basic Classes, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section 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 (@pxref{Mason}) include @samp{<%init>...</%init>} and
|
||
@samp{<%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 @code{:save-matches}. If supplied and non-nil, it
|
||
causes the regular expression @code{:back}, before being searched for,
|
||
to be formatted by replacing all strings of the form @samp{~@var{N}}
|
||
(where @var{N} is an integer) with the corresponding numbered
|
||
subexpression of the match for @code{:front}. As an example, here is an
|
||
excerpt from the @code{here-doc} submode class. @xref{Here-documents},
|
||
for more information about this submode.
|
||
|
||
@lisp
|
||
:front "<<\\([a-zA-Z0-9_-]+\\)"
|
||
:back "^~1$"
|
||
:save-matches 1
|
||
@end lisp
|
||
|
||
The regular expression for @code{:front} matches @samp{<<} 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
|
||
@samp{\(...\)}. Then, because the value of @code{:save-matches} is
|
||
present and non-nil, the string @samp{~1} is replaced in the value of
|
||
@code{:back} by the name of the here-document, thus creating a regular
|
||
expression to match the correct ending delimiter.
|
||
|
||
|
||
@node Region Placement, Submode Groups, Paired Delimiters, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section Placing Submode Regions Precisely
|
||
|
||
Normally, a submode region begins immediately after the end of the
|
||
string matching the @code{:front} regular expression and ends
|
||
immediately before the beginning of the string matching the @code{:back}
|
||
regular expression. This can be changed with the keywords
|
||
@code{:include-front} and @code{:include-back}. If their arguments are
|
||
@code{nil}, or they do not appear, the default behavior is unchanged.
|
||
But if the argument of @code{:include-front} (respectively,
|
||
@code{:include-back}) is non-nil, the submode region will begin
|
||
(respectively, end) immediately before (respectively, after) the string
|
||
matching the @code{:front} (respectively, @code{:back}) regular
|
||
expression. In other words, these keywords specify whether or not the
|
||
delimiter strings are @emph{included} in the submode region.
|
||
|
||
When @code{:front} and @code{:back} are regexps, the delimiter is
|
||
normally considered to be the entire matched region. This can be
|
||
changed using the @code{:front-match} and @code{: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
|
||
@code{:front-offset} and @code{:back-offset}, which both take integers
|
||
as arguments. The argument of @code{:front-offset} (respectively,
|
||
@code{: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
|
||
@code{:include-front} is nil or unsupplied and @code{:front-offset} is
|
||
2, the submode region will begin two characters after the end of the
|
||
match for @code{:front}, and if @code{:include-back} is non-nil and
|
||
@code{:back-offset} is -1, the region will end one character before the
|
||
end of the match for @code{:back}.
|
||
|
||
In addition to integers, the arguments of @code{:front-offset} and
|
||
@code{: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
|
||
@code{here-doc} submode class:
|
||
|
||
@lisp
|
||
:front "<<\\([a-zA-Z0-9_-]+\\)"
|
||
:front-offset (end-of-line 1)
|
||
:back "^~1$"
|
||
:save-matches 1
|
||
@end lisp
|
||
|
||
Here the value of @code{:front-offset} is the list @code{(end-of-line
|
||
1)}, meaning that from the end of the match for @code{: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 @code{:back} should not be able to start a new submode region,
|
||
set the @code{:end-not-begin} keyword to non-nil.
|
||
|
||
@node Submode Groups, Calculated Submodes, Region Placement, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section 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 @samp{<%perl>...</%perl>}, inline output expressions bounded by
|
||
@samp{<%...%>}, and single lines of code which simply begin with a
|
||
@samp{%} character. In cases like these, it is possible to specify an
|
||
``umbrella'' class, to turn all these classes on or off together.
|
||
|
||
@defun mmm-add-group @var{group} @var{classes}
|
||
The submode classes @var{classes}, which should be a list of lists,
|
||
similar to what might be passed to @code{mmm-add-classes}, are added
|
||
just as by that function. Furthermore, another class named
|
||
@var{group} is added, which encompasses all the classes in
|
||
@var{classes}.
|
||
@end defun
|
||
|
||
Technically, an group class is specified with a @code{:classes} keyword
|
||
argument, and the subsidiary classes are given a non-nil @code{:private}
|
||
keyword argument to make them invisible. But in general, all you should
|
||
ever need to know is how to invoke the function above.
|
||
|
||
@defun mmm-add-to-group @var{group} @var{classes}
|
||
Adds a list of classes to an already existing group. This can be
|
||
used, for instance, to add a new quoting definition to @var{html-js}
|
||
using this example to add the quote characters ``%=%'':
|
||
|
||
@lisp
|
||
(mmm-add-to-group 'html-js '((js-html
|
||
:submode javascript
|
||
:face mmm-code-submode-face
|
||
:front "%=%"
|
||
:back "%=%"
|
||
:end-not-begin t)))
|
||
@end lisp
|
||
@end defun
|
||
|
||
|
||
@node Calculated Submodes, Calculated Faces, Submode Groups, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section Calculating the Correct Submode
|
||
|
||
In most cases, the author of a submode class will know in advance what
|
||
major mode to use, such as @code{text-mode} or @code{c++-mode}. If
|
||
there are multiple possible modes that the user might desire, then
|
||
@code{mmm-major-mode-preferences} should be used (@pxref{Preferred
|
||
Modes}). The function @code{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 @code{here-doc} class
|
||
is one of these. In such cases, instead of the @code{:submode} keyword,
|
||
the @code{: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 @code{:front}, and
|
||
is passed one argument: a string representing the front delimiter.
|
||
Normally this string is simply whatever was matched by @code{:front},
|
||
but this can be changed with the keyword @code{:front-form}
|
||
(@pxref{Delimiters}). The function should then return a symbol
|
||
that would be a valid argument to @code{: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 @code{(signal 'mmm-no-matching-submode nil)}.
|
||
|
||
Since here-documents can contain code in any language, the
|
||
@code{here-doc} submode class uses @code{:match-submode} rather than
|
||
@code{:submode}. The function it uses is @code{mmm-here-doc-get-mode},
|
||
defined in @file{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 @code{perl-mode} (or @code{cperl-mode}):
|
||
|
||
@example
|
||
print <<PERL;
|
||
s/foo/bar/g;
|
||
PERL
|
||
@end example
|
||
|
||
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 @samp{mmm-} followed by the name of the submode class, to
|
||
avoid namespace conflicts.
|
||
|
||
|
||
@node Calculated Faces, Insertion Commands, Calculated Submodes, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section Calculating the Correct Highlight Face
|
||
|
||
As explained in @ref{Basic Classes}, the keyword @code{:face} should be
|
||
used to specify which of the standard submode faces (@pxref{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 @code{:face} is @code{:match-face}. Its value can be a
|
||
function, which is called with one argument---the form of the front
|
||
delimiter, as with @code{:match-submode}---and should return the face to
|
||
use. A more common value for @code{:match-face} is an association list,
|
||
a list of pairs @code{(@var{delim} . @var{face})}, each specifying that
|
||
if the delimiter is @var{delim}, the corresponding region should be
|
||
highlighted with @var{face}. For example, here is an excerpt from the
|
||
@code{embperl} submode class:
|
||
|
||
@lisp
|
||
: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))
|
||
@end lisp
|
||
|
||
Thus, regions beginning with @samp{[+} are highlighted as output
|
||
expressions, which they are, while @samp{[-} and @samp{[*} regions are
|
||
highlighted as simple executed code, and so on. Note that
|
||
@var{mmm-submode-decoration-level} must be set to 2 (high decoration)
|
||
for different faces to be displayed.
|
||
|
||
|
||
@node Insertion Commands, Region Names, Calculated Faces, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section Specifying Insertion Commands
|
||
|
||
As described in @ref{Insertion}, submode classes can specify key
|
||
sequences which automatically insert submode regions, with delimiters
|
||
already in place. This is done by the keyword argument @code{: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 @code{embperl} submode class:
|
||
|
||
@lisp
|
||
(?p embperl "Region Type (Character): "
|
||
@@ "[" str @@ " " _ " " @@ str "]" @@)
|
||
@end lisp
|
||
|
||
As you can see, the specifier is a list. The first element of the list
|
||
is the character @samp{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 @samp{?p} and
|
||
function keys such as @samp{return}. It can also be a dotted pair in
|
||
which the first element is a modifier symbol such as @code{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 @code{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 @code{str}. The final
|
||
location of the point (or the text around which the region is to be
|
||
wrapped) is marked with a single underscore @samp{_}. 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 @kbd{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 @kbd{C-c % +} for @samp{[+...+]} regions, @kbd{C-c %
|
||
-} for @samp{[-...-]} 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:
|
||
|
||
@lisp
|
||
(?+ embperl+ ?p . "+")
|
||
@end lisp
|
||
|
||
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 (@code{?p}), but to pass it the
|
||
fourth (dotted) element (@code{"+"}) as the `str' variable; the user is
|
||
not prompted.
|
||
|
||
|
||
@node Region Names, Other Hooks, Insertion Commands, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section 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 @code{: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
|
||
@code{:save-name} has a non-nil value, in which case expressions such
|
||
as @samp{~1} are substituted with the corresponding matched
|
||
subexpression from @code{:front}. This is the same as how
|
||
@code{:back} is interpreted when @code{:save-matches} is non-nil.
|
||
|
||
As a special optimization for region insertion (@pxref{Insertion
|
||
Commands}), the argument @code{: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.
|
||
|
||
|
||
@node Other Hooks, Delimiters, Region Names, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section 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 @code{:front} and @code{: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 @code{:front-verify} and @code{:back-verify}, if
|
||
supplied, may be functions which are invoked after a match is found for
|
||
@code{:front} or @code{:back}, respectively, and should inspect the
|
||
match data (such as with @code{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 @code{: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 @code{:handler} is supplied, it overrides any other
|
||
processing and is called, and passed all other class keyword arguments,
|
||
instead of @code{mmm-ify} to create submode regions. If you need to
|
||
write a handler function, I suggest looking at the source for
|
||
@code{mmm-ify} to get an idea of what must be done.
|
||
|
||
|
||
@node Delimiters, Misc Keywords, Other Hooks, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section 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 @code{: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 @code{:back}. You can supply offsets from
|
||
these positions using the keyword arguments @code{:front-delim} and
|
||
@code{:back-delim}, which take values of the same sort as
|
||
@code{:front-offset} and @code{: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:
|
||
|
||
@itemize
|
||
@item
|
||
If the delimiter syntax which specifies the submode regions is
|
||
something @emph{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 @xref{Mason}, @xref{Embperl}, and @xref{ePerl}.
|
||
It is also the case for literate programming such as @xref{Noweb}.
|
||
This is the default behavior. The non-mode used is controlled by the
|
||
variable @code{mmm-delimiter-mode}, which defaults to
|
||
fundamental-mode.
|
||
|
||
@item
|
||
If, on the other hand, the delimiter syntax and inclusion of different
|
||
modes is an @emph{intrinsic part} of the primary mode, then the
|
||
delimiter regions should remain in the primary mode. This is the
|
||
case, for example, with @xref{Embedded CSS}, and @xref{Javascript},
|
||
since the @code{<style>} and @code{<script>} tags are perfectly valid
|
||
HTML. In this case, you should give the keyword parameter
|
||
@code{:delimiter-mode} with a value of @code{nil}, meaning to use the
|
||
primary mode.
|
||
@end itemize
|
||
|
||
The keyword parameter @code{: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 @code{:front-face} and @code{:back-face} may be
|
||
faces specifying how to highlight these regions under high
|
||
decoration. Under low decoration, the value of the variable
|
||
@code{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 @code{(regexp-quote (match-string 0))} after each match
|
||
is found.
|
||
|
||
You can customize this with the keyword argument @code{:front-form}
|
||
(respectively, @code{: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
|
||
@code{:front-form} or @code{: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.
|
||
|
||
|
||
@node Misc Keywords, , Delimiters, Writing Classes
|
||
@comment node-name, next, previous, up
|
||
@section Miscellaneous Other Keyword Arguments
|
||
|
||
You can specify whether delimiter searches should be case-sensitive with
|
||
the keyword argument @code{:case-fold-search}. It defaults to @code{t},
|
||
meaning that case should be ignored. See the documentation for the
|
||
variable @code{case-fold-search}.
|
||
|
||
@node Indices, , Writing Classes, Top
|
||
@comment node-name, next, previous, up
|
||
@chapter 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.
|
||
@end menu
|
||
|
||
@node Concept Index, Function Index, Indices, Indices
|
||
@comment node-name, next, previous, up
|
||
@section Concept Index
|
||
|
||
@printindex cp
|
||
|
||
|
||
@node Function Index, Keystroke Index, Concept Index, Indices
|
||
@comment node-name, next, previous, up
|
||
@section Function and Variable Index
|
||
|
||
@printindex fn
|
||
|
||
|
||
@node Keystroke Index, , Function Index, Indices
|
||
@comment node-name, next, previous, up
|
||
@section Keystroke Index
|
||
|
||
@printindex ky
|
||
|
||
|
||
@bye
|
||
|
||
@c Local Variables:
|
||
@c mode: texinfo
|
||
@c mode: font-lock
|
||
@c mode: outline-minor
|
||
@c End:
|