diff options
Diffstat (limited to 'contrib/mmm/mmm.texinfo')
-rw-r--r-- | contrib/mmm/mmm.texinfo | 2117 |
1 files changed, 2117 insertions, 0 deletions
diff --git a/contrib/mmm/mmm.texinfo b/contrib/mmm/mmm.texinfo new file mode 100644 index 00000000..aa0b0eaf --- /dev/null +++ b/contrib/mmm/mmm.texinfo @@ -0,0 +1,2117 @@ +\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 + +@include version.texi + +@ifinfo +This is edition @value{EDITION} of the MMM Mode Manual, last updated +@value{UPDATED}. It documents version @value{VERSION} of MMM Mode. + +Copyright 2000 Michael Abraham Shulman. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@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 +@subtitle Edition @value{EDITION} +@subtitle @value{UPDATED} +@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. + +This is edition @value{EDITION} of the MMM Mode Manual, last updated +@value{UPDATED}, which documents version @value{VERSION} of MMM Mode. + +@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ø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: |