diff options
Diffstat (limited to 'contrib/mmm/mmm.texinfo')
| -rw-r--r-- | contrib/mmm/mmm.texinfo | 2117 |
1 files changed, 0 insertions, 2117 deletions
diff --git a/contrib/mmm/mmm.texinfo b/contrib/mmm/mmm.texinfo deleted file mode 100644 index aa0b0eaf..00000000 --- a/contrib/mmm/mmm.texinfo +++ /dev/null @@ -1,2117 +0,0 @@ -\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: |