4 @settitle MMM Mode Manual
7 @set MASON_VERSION 0.896
9 @dircategory GNU Emacs Lisp
11 * MMM-Mode: (mmm). Multiple Major Modes for Emacs
17 This is edition @value{EDITION} of the MMM Mode Manual, last updated
18 @value{UPDATED}. It documents version @value{VERSION} of MMM Mode.
20 Copyright 2000 Michael Abraham Shulman.
22 Permission is granted to make and distribute verbatim copies of this
23 manual provided the copyright notice and this permission notice are
24 preserved on all copies.
27 Permission is granted to process this file through TeX and print the
28 results, provided the printed document carries a copying permission
29 notice identical to this one except for the removal of this paragraph
30 (this paragraph not being relevant to the printed manual).
33 Permission is granted to copy and distribute modified versions of this
34 manual under the conditions for verbatim copying, provided also that the
35 sections entitled ``Copying'' and ``GNU General Public License'' are
36 included exactly as in the original, and provided that the entire
37 resulting derived work is distributed under the terms of a permission
38 notice identical to this one.
40 Permission is granted to copy and distribute translations of this manual
41 into another language, under the above conditions for modified versions,
42 except that this permission notice may be stated in a translation
43 approved by the Free Software Foundation.
48 @title MMM Mode Manual
49 @subtitle Multiple Major Modes for Emacs
50 @subtitle Edition @value{EDITION}
51 @subtitle @value{UPDATED}
52 @author Michael Abraham Shulman
54 @vskip 0pt plus 1filll
55 Copyright @copyright{} 2000 Michael Abraham Shulman.
57 Permission is granted to make and distribute verbatim copies of this
58 manual provided the copyright notice and this permission notice are
59 preserved on all copies.
61 Permission is granted to copy and distribute modified versions of this
62 manual under the conditions for verbatim copying, provided also that the
63 sections entitled ``Copying'' and ``GNU General Public License'' are
64 included exactly as in the original, and provided that the entire
65 resulting derived work is distributed under the terms of a permission
66 notice identical to this one.
68 Permission is granted to copy and distribute translations of this manual
69 into another language, under the above conditions for modified versions,
70 except that this permission notice may be stated in a translation
71 approved by the Free Software Foundation.
76 @node Top, Overview, (dir), (dir)
79 MMM Mode is a minor mode for Emacs which allows Multiple Major Modes to
80 coexist in a single buffer.
82 This is edition @value{EDITION} of the MMM Mode Manual, last updated
83 @value{UPDATED}, which documents version @value{VERSION} of MMM Mode.
88 * Overview:: An overview and introduction to MMM Mode.
89 * Basics:: The basics of how to use it.
90 * Customizing:: Customizing how it works to your needs.
91 * Supplied Classes:: The supplied submode classes.
92 * Writing Classes:: Writing your own submode classes.
93 * Indices:: Just that.
96 --- The Detailed Node Listing ---
100 * Basic Concepts:: A simple explanation of how it works.
101 * Installation:: How to install MMM Mode.
102 * Quick Start:: Getting started using MMM Mode quickly.
106 * MMM Minor Mode:: The Emacs minor mode that manages it all.
107 * Submode Classes:: What they are and how to use them.
108 * Selecting Classes:: How MMM Mode knows what classes to use.
109 * Insertion:: Inserting new submode regions automatically.
110 * Re-parsing:: Re-scanning for submode regions.
111 * Interactive:: Adding submode regions manually.
112 * Global Mode:: Turning MMM Mode on automatically.
116 * Enabling MMM Mode:: Turning MMM Mode on and off.
117 * MMM Mode Keys:: Default key bindings in MMM Mode.
119 How MMM Mode selects submode classes
121 * File Classes:: Classes for a single file.
122 * Mode-Ext Classes:: Classes for a given mode or extension.
123 * Global Classes:: Classes for all MMM Mode buffers.
127 * Major Mode Hook:: Using MMM's Major Mode Hook
131 * Region Coloring:: Changing or removing background colors.
132 * Preferred Modes:: Choosing which major modes to use.
133 * Mode Line:: What is displayed in the mode line.
134 * Key Bindings:: Customizing the MMM Mode key bindings.
135 * Local Variables:: What local variables are saved for submodes.
136 * Changing Classes:: Changing the supplied submode classes.
137 * Hooks:: How to make MMM Mode run your code.
139 Supplied Submode Classes
141 * Mason:: Mason server-side Perl in HTML.
142 * File Variables:: Elisp code in File Variables.
143 * Here-documents:: Code in shell and Perl here-documents.
144 * Javascript:: Javascript embedded in HTML.
145 * Embedded CSS:: CSS Styles embedded in HTML.
146 * Embperl:: Another syntax for Perl in HTML.
147 * ePerl:: A general Perl-embedding syntax.
148 * JSP:: Java code embedded in HTML.
149 * RPM:: Shell scripts in RPM Spec Files.
150 * Noweb:: Noweb literate programs.
152 Writing Submode Classes
154 * Basic Classes:: Writing a simple submode class.
155 * Paired Delimiters:: Matching paired delimiters.
156 * Region Placement:: Placing the region more accurately.
157 * Submode Groups:: Grouping several classes together.
158 * Calculated Submodes:: Deciding the submode at run-time.
159 * Calculated Faces:: Deciding the display face at run-time.
160 * Insertion Commands:: Inserting regions automatically.
161 * Region Names:: Naming regions for syntax grouping.
162 * Other Hooks:: Running code at arbitrary points.
163 * Delimiters:: Controlling delimiter overlays.
164 * Misc Keywords:: Other miscellaneous options.
168 * Concept Index:: Index of MMM Mode Concepts.
169 * Function Index:: Index of functions and variables.
170 * Keystroke Index:: Index of key bindings in MMM Mode.
175 @node Overview, Basics, Top, Top
176 @comment node-name, next, previous, up
177 @chapter Overview of MMM Mode
178 @cindex overview of mmm-mode
179 @cindex mmm-mode, overview of
181 MMM Mode is a minor mode for Emacs which allows Multiple Major Modes to
182 coexist in a single buffer. The name is an abbreviation of `Multiple
183 Major Modes'@footnote{The name is derived from @file{mmm.el} for XEmacs
184 by Gongquan Chen <chen@@posc.org>, from which MMM Mode was adapted.}. A
185 major mode is a customization of Emacs for editing a certain type of
186 text, such as code for a specific programming language. @xref{Major
187 Modes, , , emacs, The Emacs Manual}, for details.
189 MMM Mode is a general extension to Emacs which is useful whenever one
190 file contains text in two or more programming languages, or that
191 should be in two or more different modes. For example:
195 CGI scripts written in any language, from Perl to PL/SQL, may want to
196 output verbatim HTML, and the writer of such scripts may want to use
197 Emacs' html-mode or sgml-mode to edit this HTML code, while remaining
198 in the appropriate programming language mode for the rest of the
199 file. @xref{Here-documents}, for example.
202 There are now many ``content delivery systems'' which turn the CGI
203 script idea around and simply add extra commands to an HTML file,
204 often in some programming language, which are interpreted on the
205 server. @xref{Mason}, @xref{Embperl}, @xref{ePerl}, @xref{JSP}.
208 HTML itself can also contain embedded languages such as Javascript and
209 CSS styles, for which Emacs has different major modes.
210 @xref{Javascript}, and @xref{Embedded CSS}, for example.
213 The idea of ``literate programming'' requires the same file to contain
214 documentation (written as text, html, latex, etc.) and code (in an
215 appropriate programming language). @xref{Noweb}, for example.
218 Emacs allows files of any type to contain `local variables', which can
219 include Emacs Lisp code to be evaluated. @xref{File Variables, , ,
220 emacs, The Emacs Manual}. It may be easier to edit this code in Emacs
221 Lisp mode than in whatever mode is used for the rest of the file.
222 @xref{File Variables}.
225 There are many more possible uses for MMM Mode. RPM spec files can
226 contain shell scripts (@pxref{RPM}). Email or newsgroup messages may
227 contain sample code. And so on. We encourage you to experiment.
231 * Basic Concepts:: A simple explanation of how it works.
232 * Installation:: How to install MMM Mode.
233 * Quick Start:: Getting started using MMM Mode quickly.
236 @node Basic Concepts, Installation, Overview, Overview
237 @comment node-name, next, previous, up
238 @section Basic Concepts
239 @cindex dominant major mode
240 @cindex major mode, dominant
241 @cindex default major mode
242 @cindex major mode, default
243 @cindex submode regions
244 @cindex regions, submode
245 @cindex overlays, submode
246 @cindex submode overlays
247 @cindex mmm-ification
249 The way MMM Mode works is as follows. Each buffer has a @dfn{dominant}
250 or @dfn{default} major mode, which is chosen as major modes normally
251 are: the user can set it interactively, or it can be chosen
252 automatically with `auto-mode-alist' (@pxref{Choosing Modes, , , emacs,
253 The Emacs Manual}). Within the file, MMM Mode creates @dfn{submode
254 regions} within which other major modes are in effect. While the point
255 is in a submode region, the following changes occur:
259 The local keymap is that of the submode. This means the key bindings for
260 the submode are available, while those of the dominant mode are not.
262 The mode line (@pxref{Mode Line, , , emacs, The Emacs Manual}) changes
263 to show which submode region is active. This can be configured; see
266 The major mode menu, both on the menu bar and the mouse popup, are that
269 Some local variables of the submode shadow those of the default mode
270 (@pxref{Local Variables}). For the user, this serves to help make Emacs
271 behave as if the submode were the major mode.
273 The syntax table and indentation are those of the submode.
275 Font-lock (@pxref{Font Lock, , , emacs, The Emacs Manual}) fontifies
276 correctly for the submode.
278 The submode regions are highlighted by a background color; see
279 @ref{Region Coloring}.
283 The submode regions are represented internally by Emacs Lisp objects
284 known as @dfn{overlays}. Some of the above are implemented by overlay
285 properties, and others are updated by an MMM Mode function in
286 `post-command-hook'. You don't need to know this to use MMM Mode, but it
287 may make any error messages you come across more understandable.
288 @xref{Overlays, , , elisp, The GNU Emacs Lisp Reference Manual}, for
289 more information on overlays.
291 Because overlays are not saved with a file, every time a file is opened,
292 they must be created. Creating submode regions is occasionally referred
293 to as @dfn{mmm-ification}. (I've never had occasion to pronounce this,
294 but if I did I would probably say `mummification'. Like what they did in
295 ancient Egypt.) You can mmm-ify a buffer interactively, but most often
296 MMM Mode will find and create submode regions automatically based on a
297 buffer's file extension, dominant mode, or local variables.
300 @node Installation, Quick Start, Basic Concepts, Overview
301 @comment node-name, next, previous, up
302 @section Installing MMM Mode
304 MMM Mode has a standard installation process. See the file INSTALL for
305 generic information on this process. To summarize, unpack the archive,
306 @command{cd} to the created MMM Mode directory, type @samp{./configure},
307 then @samp{make}, then @samp{make install}. If all goes correctly, this
308 will compile the MMM Mode elisp files, install them in your local
309 site-lisp directory, and install the MMM Mode info file @file{mmm.info}
310 in your local info directory.
312 Now you need to configure your Emacs initialization file (usually
313 @file{~/.emacs}) to use MMM Mode. First, Emacs has to know where to
314 find MMM Mode. In other words, the MMM Mode directory has to be in
315 @code{load-path}. This can be done in the parent directory's
316 @file{subdirs.el} file, or in the init file with a line such as:
319 (add-to-list 'load-path "/path/to/site-lisp/mmm/")
322 Once @code{load-path} is configured, MMM Mode must be loaded. You can
323 load all of MMM Mode with the line
330 but if you use MMM Mode only rarely, it may not be desirable to load all
331 of it at the beginning of every editing session. You can load just
332 enough of MMM Mode so it will turn itself on when necessary and load the
333 rest of itself, by using instead the line
340 in your initialization file.
342 One more thing you may want to do right now is to set the variable
343 @code{mmm-global-mode}. If this variable is @code{nil} (the default),
344 MMM Mode will never turn itself on. If it is @code{t}, MMM Mode will
345 turn itself on in every buffer. Probably the most useful value for it,
346 however, is the symbol @code{maybe} (actually, anything that is not
347 @code{nil} and not @code{t}), which causes MMM Mode to turn itself on in
348 precisely those buffers where it would be useful. You can do this with
352 (setq mmm-global-mode 'maybe)
356 in your initialization file. @xref{Global Mode}, for more detailed
360 @node Quick Start, , Installation, Overview
361 @comment node-name, next, previous, up
362 @section Getting Started Quickly
364 Perhaps the simplest way to create submode regions is to do it
365 interactively by specifying a region. First you must turn MMM Mode
366 on---say, with @kbd{M-x mmm-mode}---then place point and mark around the
367 area you want to make into a submode region, type @kbd{C-c % C-r}, and
368 enter the desired major mode. @xref{Interactive}, for more details.
370 A better way to add submode regions is by using submode classes, which
371 store a lot of useful information for MMM Mode about how to add and
372 manipulate the regions created. @xref{Submode Classes}, for more
373 details. There are several sample submode classes that come with MMM
374 Mode, which are documented later in this manual. Look through these and
375 determine if one of them fits your needs. If so, I suggest reading the
376 comments on that mode. Then come back here to find out to use it.
378 To apply a submode class to a buffer interactively, turn MMM Mode on as
379 above, then type @kbd{C-c % C-c} and enter the name of the class.
380 Submode regions should be added automatically, if there are any regions
381 in the buffer appropriate to the submode class.
383 If you want a given file to always use a given submode class, you can
384 express this in a file variable: add a line containing the string
385 @samp{-*- mmm-classes: @var{class} -*-} at the top of the file.
386 @xref{File Variables, , , emacs, The Emacs Manual}, for more information
387 and other methods. Now whenever MMM Mode is turned on in that file, it
388 will be mmm-ified according to @var{class}. If @code{mmm-global-mode} is
389 non-nil, then MMM Mode will turn itself on whenever a file with a
390 @code{mmm-classes} local variable is opened. @xref{Global Mode}, for more
393 If you want a submode class to apply to @emph{all} files in a certain
394 major mode or with a certain extension, add a line such as this to your
398 (mmm-add-mode-ext-class @var{mode} @var{extension} @var{class})
402 After this call, any file opened whose name matches the regular
403 expression @var{extension} @emph{and} whose default mode is @var{mode}
404 will be automatically mmm-ified according to @var{class} (assuming
405 @code{mmm-global-mode} is non-nil). If one of @var{extension} or
406 @var{mode} is @code{nil}, a file need only satisfy the other one to be
409 You can now read the rest of this manual to learn more about how MMM
410 Mode works and how to configure it to your preferences. If none of the
411 supplied submode classes fit your needs, then you can try to write your
412 own. @xref{Writing Classes}, for more information.
414 @node Basics, Customizing, Overview, Top
415 @comment node-name, next, previous, up
416 @chapter MMM Mode Basics
418 This chapter explains the most important parts of how to use MMM Mode.
421 * MMM Minor Mode:: The Emacs minor mode that manages it all.
422 * Submode Classes:: What they are and how to use them.
423 * Selecting Classes:: How MMM Mode knows what classes to use.
424 * Insertion:: Inserting new submode regions automatically.
425 * Re-parsing:: Re-scanning for submode regions.
426 * Interactive:: Adding submode regions manually.
427 * Global Mode:: Turning MMM Mode on automatically.
430 @node MMM Minor Mode, Submode Classes, Basics, Basics
431 @comment node-name, next, previous, up
432 @section The MMM Minor Mode
433 @cindex mode, mmm minor
434 @cindex minor mode, mmm
435 @cindex mmm minor mode
437 An Emacs minor mode is an optional feature which can be turned on or off
438 in a given buffer, independently of the major mode. @xref{Minor Modes, ,
439 , emacs, The Emacs Manual}. MMM Mode is implemented as a minor mode
440 which manages the submode regions. This minor mode must be turned on in
441 a buffer for submode regions to be effective. When activated, the MMM
442 Minor mode is denoted by @samp{MMM} in the mode line (@pxref{Mode
446 * Enabling MMM Mode:: Turning MMM Mode on and off.
447 * MMM Mode Keys:: Default key bindings in MMM Mode.
451 @node Enabling MMM Mode, MMM Mode Keys, MMM Minor Mode, MMM Minor Mode
452 @comment node-name, next, previous, up
453 @subsection Enabling MMM Mode
454 @cindex mmm mode, turning on
455 @cindex mmm mode, turning off
456 @cindex turning on mmm mode
457 @cindex turning off mmm mode
458 @cindex mmm mode, enabling
459 @cindex mmm mode, disabling
460 @cindex enabling mmm mode
461 @cindex disabling mmm mode
463 If @code{mmm-global-mode} is non-@code{nil} (@pxref{Global Mode}),
464 then the MMM minor mode will be turned on automatically whenever a file
465 with associated submode classes is opened (@pxref{Selecting Classes}).
466 It is also turned on by interactive mmm-ification (@pxref{Interactive}),
467 although the interactive commands do not have key bindings when it is
468 not on and must be invoked via @kbd{M-x}. You can also turn it on (or
469 off) manually with @kbd{M-x mmm-mode}, in which case it applies all
470 submode classes associated with the buffer. Turning MMM Mode off
471 automatically removes all submode regions from the buffer.
473 @deffn Command mmm-mode @var{arg}
474 Toggle the state of MMM Mode in the current buffer. If @var{arg} is
475 supplied, turn MMM Mode on if and only if @var{arg} is positive.
479 Turn MMM Mode on unconditionally in the current buffer.
483 Turn MMM Mode off unconditionally in the current buffer.
487 This variable represents whether MMM Mode is on in the current buffer.
488 Do not set this variable directly; use one of the above functions.
492 @node MMM Mode Keys, , Enabling MMM Mode, MMM Minor Mode
493 @comment node-name, next, previous, up
494 @subsection Key Bindings in MMM Mode
495 @cindex mmm mode key bindings
496 @cindex key bindings in mmm mode
497 @findex mmm-insertion-help
500 When MMM Mode is on, it defines a number of key bindings. By default,
501 these are bound after the prefix sequence @kbd{C-c %}. Minor mode
502 keymaps are supposed to use @kbd{C-c @var{punctuation}} sequences, and I
503 find this one to be a good mnemonic because @samp{%} is used by Mason to
504 denote special tags. This prefix key can be customized; @ref{Key
507 There are two types of key bindings in MMM Mode: @dfn{commands} and
508 @dfn{insertions}. Command bindings run MMM Mode interactive functions to
509 do things like re-parse the buffer or end the current submode region,
510 and are defined statically as normal Emacs key-bindings. Insertion
511 bindings insert submode region skeletons with delimiters into the
512 buffer, and are defined dynamically, according to which submode classes
513 (@pxref{Submode Classes}) are in effect, via a keymap default binding.
515 To distinguish between the two, MMM Mode uses distinct modifier keys for
516 each. By default, command bindings use the control key (e.g. @kbd{C-c %
517 C-b} re-parses the buffer), and insertion bindings do not (e.g. @kbd{C-c
518 % p}, when the Mason class is in effect, inserts a
519 @samp{<%perl>...</%perl>} region). This makes the command bindings
520 different from in previous versions, however, so the variable
521 @code{mmm-use-old-bindings} is provided. If this variable is set to `t'
522 before MMM Mode is loaded, the bindings will be reversed: insertion
523 bindings will use the control key and command bindings will not.
525 Normally, Emacs gives help on a prefix command if you type @kbd{C-h}
526 after that command (e.g. @kbd{C-x C-h} displays all key bindings
527 starting with @kbd{C-x}). Because of how insertion bindings are
528 implemented dynamically with a default binding, they do not show up when
529 you hit @kbd{C-c % C-h}. For this reason, MMM Mode defines the command
530 @kbd{C-c % h} which displays a list of all currently valid insertion key
531 sequences. If you use the defaults for command and insertion bindings,
532 the @kbd{C-h} and @kbd{h} should be mnemonic.
534 In the rest of this manual, I will assume you are using the defaults for
535 the mode prefix (@kbd{C-c %}) and the command and insertion modifiers.
536 You can customize them, however; @ref{Key Bindings}.
539 @node Submode Classes, Selecting Classes, MMM Minor Mode, Basics
540 @comment node-name, next, previous, up
541 @section Understanding Submode Classes
542 @cindex submode classes
543 @cindex classes, submode
545 A submode class represents a ``type'' of submode region. It specifies
546 how to find the regions, what their delimiters look like, what submode
547 they should be, how to insert them, and how they behave in other ways.
548 It is represented by a symbol, such as @code{mason} or
551 For example, in the Mason set of classes, there is one class
552 representing all @samp{<%...%>} inline Perl regions, and one
553 representing regions such as @samp{<%perl>...</%perl>},
554 @samp{<%init>...</%init>}, and so on. These are different to Mason, but
555 to Emacs they are all just Perl sections, so they are covered by the
558 But it would be tedious if whenever we wanted to use the Mason classes,
559 we had to specify both of these. (Actually, this is a simplification:
560 there are some half a dozen Mason submode classes.) So submode classes
561 can also ``group'' others together, and we can refer to the @code{mason}
562 class and mean all of them.
564 The way a submode class is used is to @dfn{apply} it to a buffer. This
565 scans the buffer for regions which should be submode regions according
566 to that class, and also remembers the class for later, so that new
567 submode regions can be inserted and scanned for later.
570 @node Selecting Classes, Insertion, Submode Classes, Basics
571 @comment node-name, next, previous, up
572 @section How MMM Mode selects submode classes
574 Submode classes that apply to a buffer come from three sources:
575 mode/extension-associated classes, file-local classes, and interactive
576 MMM-ification (@pxref{Interactive}). Whenever MMM Mode is turned on in a
577 buffer (@pxref{MMM Minor Mode}, and @ref{Global Mode}), it inspects the
578 value of two variables to determine which classes to automatically apply
579 to the buffer. This covers the first two sources; the latter is covered
583 * File Classes:: Classes for a single file.
584 * Mode-Ext Classes:: Classes for a given mode or extension.
585 * Global Classes:: Classes for all MMM Mode buffers.
589 @node File Classes, Mode-Ext Classes, Selecting Classes, Selecting Classes
590 @comment node-name, next, previous, up
591 @subsection File-Local Submode Classes
594 This variable is always buffer-local when set. Its value should be
595 either a single symbol or a list of symbols. Each symbol represents a
596 submode class that is applied to the buffer.
599 @code{mmm-classes} is usually set in a file local variables list.
600 @xref{File Variables, , , emacs, The Emacs Manual}. The easiest way to
601 do this is for the first line of the file to contain the string
602 @samp{-*- mmm-classes: @var{classes} -*-}, where @var{classes} is the
603 desired value of @code{mmm-classes} for the file in question. It can
604 also be done with a local variables list at the end of the file.
607 @node Mode-Ext Classes, Global Classes, File Classes, Selecting Classes
608 @comment node-name, next, previous, up
609 @subsection Submode Classes Associated with Modes and Extensions
611 @defopt mmm-mode-ext-classes-alist
612 This global variable associates certain submode classes with major modes
613 and/or file extensions. Its value is a list of elements of the form
614 @code{(@var{mode} @var{ext} @var{class})}. Any buffer whose major mode
615 is @var{mode} (a symbol) @emph{and} whose file name matches @var{ext} (a
616 regular expression) will automatically have the submode class
617 @var{class} applied to it.
619 If @var{mode} is @code{nil}, then only @var{ext} is considered to
620 determine if a buffer fits the criteria, and vice versa. Thus if both
621 @var{mode} and @var{ext} are nil, then @var{class} is applied to
622 @emph{all} buffers in which MMM Mode is on. Note that @var{ext} can be
623 any regular expression, although its name indicates that it most often
624 refers to the file extension.
626 If @var{class} is the symbol @code{t}, then no submode class is actually
627 applied for this association. However, if @code{mmm-global-mode} is
628 non-@code{nil} and non-@code{t}, MMM Mode will be turned on in matching
629 buffers even if there are no actual submode classes being applied.
633 @defun mmm-add-mode-ext-class @var{mode} @var{ext} @var{class}
634 This function adds an element to @code{mmm-mode-ext-classes-alist},
635 associating the submode class @var{class} with the major mode @var{mode}
636 and extension @var{ext}.
638 Older versions of MMM Mode required this function to be used to control
639 the value of @code{mmm-mode-ext-classes-alist}, rather than setting it
640 directly. In this version it is provided purely for convenience and
641 backward compatibility.
645 @node Global Classes, , Mode-Ext Classes, Selecting Classes
646 @comment node-name, next, previous, up
647 @subsection Globally Applied Classes and the Universal Class
649 In addition to file-local and mode-ext-associated submode classes, MMM
650 Mode also allows you to specify that certain submode classes apply to
651 @emph{all} buffers in which MMM Mode is enabled.
653 @defopt mmm-global-classes
654 This variable's value should be a list of submode classes that apply to
655 all buffers with MMM Mode on. It can be overriden in a file local
656 variables list, such as to disable global class for a specific file.
657 Its default value is @code{(universal)}.
660 The default global class is the ``universal class'', which is defined in
661 the file @file{mmm-univ.el} (loaded automatically), and allows the
662 author of text to specify that a certain section of it be in a specific
663 major mode. Thus, for example, when writing an email message that
664 includes sample code, the author can allow readers of the message (who
665 use emacs and MMM) to view the code in the appropriate major mode. The
666 syntax used is @samp{@{%@var{mode}%@} ... @{%/@var{mode}%@}}, where
667 @var{mode} should be the name of the major mode, with or without the
668 customary @samp{-mode} suffix: for example, both @samp{cperl} and
669 @samp{cperl-mode} are acceptable.
671 The universal class also defines an insertion key, @samp{/}, which
672 prompts for the submode to use. @xref{Insertion}. The universal class
673 is most useful when @code{mmm-global-mode} is set to @code{t};
677 @node Insertion, Re-parsing, Selecting Classes, Basics
678 @comment node-name, next, previous, up
679 @section Inserting new submode regions
681 So much for noticing submode regions already present when you open a
682 file. When editing a file with MMM Mode on, you will often want to add a
683 new submode region. MMM Mode provides several facilities to help you.
684 The simplest is to just hit a few keys and have the region and its
685 delimiters inserted for you.
687 Each submode class can define an association of keystrokes with
688 ``skeletons'' to insert a submode region. If there are several submode
689 classes enabled in a buffer, it is conceivable that the keys they use
690 for insertion might conflict, but unlikely as most buffers will not use
691 more than one or two submode classes groups.
693 As an example of how insertion works, consider the Mason classes. In a
694 buffer with MMM Mode enabled and Mason associated, the key sequence
695 @kbd{C-c % p} inserts the following perl section (the semicolon is to
696 prevent CPerl Mode from getting confused---@pxref{Mason}):
704 In this schematic representation, the string @samp{-!-} represents the
705 position of point (the cursor), @samp{-<-} represents the beginning of
706 the submode region, and @samp{->-} its end.
708 All insertion keys come after the MMM Mode prefix keys (by default
709 @kbd{C-c %}; @pxref{Key Bindings}) and are by default single characters
710 such as @kbd{p}, @kbd{%}, and @kbd{i}. To avoid confusion, all the MMM
711 Mode commands are bound by default to control characters (after the same
712 prefix keys), such as @kbd{C-b}, @kbd{C-%} and @kbd{C-r}. This is a
713 change from earlier versions of MMM Mode, and can be customized; see
716 To find out what insertion keys are available, consult the documentation
717 for the submode class you are using. If it is one of the classes
718 supplied with MMM Mode, you can find it in this Info file.
720 Because insertion keys are implemented with a ``default binding'' for
721 flexibility, they do not show up in the output of @kbd{C-h m} and cannot
722 be found with @kbd{C-h k}. For this reason, MMM Mode supplies the
723 command @kbd{C-c % h} (@code{mmm-insertion-help} to view the available
727 @node Re-parsing, Interactive, Insertion, Basics
728 @comment node-name, next, previous, up
729 @section Re-Parsing Submode Regions
730 @cindex re-parsing submode regions
731 @cindex parsing submode regions
732 @cindex submode regions, re-parsing
733 @cindex regions, submode, re-parsing
734 @cindex submode regions, clearing
735 @cindex clearing submode regions
736 @cindex regions, submode, clearing
743 Describe @code{mmm-parse-buffer}, @code{mmm-parse-region},
744 @code{mmm-parse-block}, and @code{mmm-clear-current-region}.
746 @node Interactive, Global Mode, Re-parsing, Basics
747 @comment node-name, next, previous, up
748 @section Interactive MMM-ification Functions
749 @cindex interactive mmm-ification
750 @cindex mmm-ification, interactive
751 @cindex mmm-ification by region
752 @cindex mmm-ification by regexp
753 @cindex mmm-ification by class
754 @cindex region, mmm-ification by
755 @cindex regexp, mmm-ification by
756 @cindex class, mmm-ification by
760 @cindex mmm-ification, interactive history
761 @cindex history of interactive mmm-ification
762 @cindex interactive mmm-ification, history of
764 There are several commands you can use to create submode regions
765 interactively, rather than by applying a submode class to a buffer.
766 These commands (in particular, @code{mmm-ify-region}), can be useful
767 when editing a file or email message containing a snippet of code in
768 some other language. Also see @ref{Global Classes}, for an alternate
769 approach to the same problem.
773 Creates a submode region between point and mark. Prompts for the submode
774 to use, which must be a valid Emacs major mode name, such as
775 @code{emacs-lisp-mode} or @code{cperl-mode}. Adds markers to the
776 interactive history. (@code{mmm-ify-region})
779 Applies an already-defined submode class to the buffer, which it prompts
780 for. Adds this class to the interactive history.
781 (@code{mmm-ify-by-class})
784 Scans the buffer for submode regions (prompts for the submode) using
785 front and back regular expressions that it also prompts for. Briefly, it
786 starts at the beginning of the buffer and searches for the front regexp.
787 If it finds a match, it searches for the back regexp. If it finds a
788 match for that as well, it makes a submode region between the two
789 matches and continues searching until no more matches are found. Adds
790 the regexps to the interactive history. (@code{mmm-ify-by-regexp})
794 These commands are also useful when designing a new submode class
795 (@pxref{Submode Classes}). Working with the regexps interactively can
796 make it easier to debug and tune the class before starting to use it on
797 automatic. All these commands also add to value of the following
800 @defvar mmm-interactive-history
801 Stores a history of all interactive mmm-ification that has been
802 performed in the current buffer. This way, for example, the re-parsing
803 functions (@pxref{Re-parsing}) will respect interactively added regions,
804 and the insertion keys for classes that were added interactively are
808 If for any reason you want to ``wipe the slate clean'', this command
809 should help you. By default, it has no key binding, so you must invoke
810 it with @kbd{M-x mmm-clear-history @key{RET}}.
812 @deffn Command mmm-clear-history
813 Clears all history of interactive mmm-ification in the current buffer.
814 This command does not affect existing submode regions; to remove them,
815 you may want to re-parse the buffer with @kbd{C-c % C-b}
816 (@code{mmm-parse-buffer}).
820 @node Global Mode, , Interactive, Basics
821 @comment node-name, next, previous, up
822 @section MMM Global Mode
823 @cindex mode, mmm global
824 @cindex global mmm mode
825 @cindex mmm global mode
826 @vindex mmm-never-modes
828 When a file has associated submode classes (@pxref{Selecting Classes}),
829 you may want MMM Mode to turn itself on and parse that file for submode
830 regions automatically whenever it is opened in an Emacs buffer. The
831 value of the following variable controls when MMM Mode turns itself on
834 @defopt mmm-global-mode
835 Do not be misled by the fact that this variable's name ends in
836 @samp{-mode}: it is not a simple on/off switch. There are three possible
837 (meanings of) values for it: @code{t}, @code{nil}, and anything else.
839 When this variable is @code{nil}, MMM Mode is never enabled
840 automatically. If it is enabled manually, such as by typing @kbd{M-x
841 mmm-mode}, any submode classes associated with the buffer will still be
844 When this variable is @code{t}, MMM Mode is enabled automatically in
845 @emph{all} buffers, including those not visiting files, except those
846 whose major mode is an element of @code{mmm-never-modes}. The default
847 value of this variable contains modes such as @code{help-mode} and
848 @code{dired-mode} in which most users would never want MMM Mode, and
849 in which MMM might cause problems.
851 When this variable is neither @code{nil} nor @code{t}, MMM Mode is
852 enabled automatically in all buffers that would have associated submode
853 classes; i.e. only if there would be something for it to do. The value
854 of @code{mmm-never-modes} is still respected, however. Note that this
855 can include buffers not visiting files, if that buffer's major mode is
856 present in @code{mmm-mode-ext-classes-alist} with a @code{nil} value for
857 @var{ext} (@pxref{Mode-Ext Classes}). Submode class values of @code{t}
858 in @code{mmm-mode-ext-classes-alist} cause MMM Mode to be enabled in
859 matching buffers, but supply no submode classes to be applied.
863 * Major Mode Hook:: Using MMM's Major Mode Hook
867 @node Major Mode Hook, , Global Mode, Global Mode
868 @comment node-name, next, previous, up
869 @subsection The Major Mode Hook
870 @cindex hook, major mode
871 @cindex major mode hook
872 @vindex mmm-major-mode-hook
874 This section is intended for users who understand Emacs Lisp and want to
875 know how MMM Global Mode is implemented, and perhaps use the same
876 technique. In fact, MMM Mode exports a hook variable that you can use
877 easily, without understanding any of the details---see below.
879 In order to enable itself in @emph{all} buffers, however, MMM Mode has
880 to hook itself into all major modes. Global Font Lock Mode from the
881 standard Emacs distribution (@pxref{Font Lock, , , emacs, The Emacs
882 Manual}) has a similar problem, and solves it by adding a function to
883 @code{change-major-mode-hook}, which is run by
884 @code{kill-all-local-variables}, which is run in turn by all major mode
885 functions at the @emph{beginning}. This function stores a list of which
886 buffers need fontification. It then adds a different function to
887 @code{post-command-hook}, which checks if the current buffer needs
888 fontification, and if so performs it. MMM Global Mode uses the same
891 In the interests of generality, and for your use, the function that MMM
892 Mode runs in @code{post-command-hook} (@code{mmm-run-major-mode-hook})
893 is not specific to MMM Mode, but rather runs the hook variable
894 @code{mmm-major-mode-hook}, which by default contains a function
895 (@code{mmm-mode-on-maybe}) which possibly turns MMM Mode on, depending
896 on the value of @code{mmm-global-mode}. Thus, to run another function
897 in all major modes, all you need to do is add it to this hook. For
898 example, the following line in an initialization file will turn on Auto
899 Fill Mode (@pxref{Auto Fill, , , emacs, The Emacs Manual}) in all
903 (add-hook 'mmm-major-mode-hook 'turn-on-auto-fill)
906 @node Customizing, Supplied Classes, Basics, Top
907 @comment node-name, next, previous, up
908 @chapter Customizing MMM Mode
910 This chapter explains how to customize the appearance and functioning of
911 MMM Mode however you want.
914 * Region Coloring:: Changing or removing background colors.
915 * Preferred Modes:: Choosing which major modes to use.
916 * Mode Line:: What is displayed in the mode line.
917 * Key Bindings:: Customizing the MMM Mode key bindings.
918 * Local Variables:: What local variables are saved for submodes.
919 * Changing Classes:: Changing the supplied submode classes.
920 * Hooks:: How to make MMM Mode run your code.
923 @node Region Coloring, Preferred Modes, Customizing, Customizing
924 @comment node-name, next, previous, up
925 @section Customizing Region Coloring
926 @cindex faces, submode
927 @cindex submode faces
928 @cindex customizing submode faces
929 @cindex default submode face
931 By default, MMM Mode highlights all submode regions with a background
932 color. There are three levels of this decoration, controlled by the
935 @defopt mmm-submode-decoration-level
936 This variable controls the level of coloring of submode regions. It
937 should be one of the integers 0, 1, or 2, representing (respectively)
938 none, low, and high coloring.
941 No coloring means exactly that. Submode regions have the same
942 background as the rest of the text. This produces the minimal
943 interference with font-lock coloration. In particular, if you want to
944 use background colors for font-lock, this may be a good idea, because
945 the submode highlight, if present, overrides any font-lock background
948 Low coloring uses the same background color for all submode regions.
949 This color is specified with the face @code{mmm-default-submode-face}
950 (@pxref{Faces, , , emacs, The Emacs Manual}) which can be customized,
951 either through the Emacs ``customize'' interface or using direct Lisp
952 commands such as @code{set-face-background}. Of course, other aspects
953 of the face can also be set, such as the foreground color, bold,
954 underline, etc. These are more likely to conflict with font-lock,
955 however, so only a background color is recommended.
957 High coloring uses multiple background colors, depending on the function
958 of the submode region. The recognized functions and their meanings are
963 Code that is executed at the beginning of (something), as initialization
967 Code that is executed at the end of (something), as some sort of clean
971 Code that provides declarations of some sort, perhaps global or local
972 arguments, variables, or methods.
975 Text that is not executed as code, but instead serves to document the
976 code around it. Submode regions of this function often use a mode such
977 as Text Mode rather than a programming language mode.
980 An expression that is evaluated and its value interpolated into the
984 Executed code not falling under any other category.
987 Submode regions not falling under any other category, such as component
992 The different background colors are provided by the faces
993 @code{mmm-@var{function}-submode-face}, which can be customized in the
994 same way as @code{mmm-default-submode-face}.
997 @node Preferred Modes, Mode Line, Region Coloring, Customizing
998 @comment node-name, next, previous, up
999 @section Preferred Major Modes
1001 Certain of the supplied submode classes know only the language that
1002 certain sections are written in, but not what major mode you prefer to
1003 use to edit such code. For example, many people prefer CPerl mode over
1004 Perl mode; you may have a special mode for Javascript or just use C++
1005 mode. This variable allows you to tell submodes such as Mason
1006 (@pxref{Mason}) and Embedded Javascript (@pxref{Javascript}) what major
1007 mode to use for the submodes:
1009 @defopt mmm-major-mode-preferences
1010 The elements of this list are cons cells of the form
1011 @code{(@var{language} . @var{mode})}. @var{language} should be a symbol
1012 such as @code{perl}, @code{html-js}, or @code{java}, while @var{mode}
1013 should be the name of a major mode such as @code{perl-mode},
1014 @code{cperl-mode}, @code{javascript-mode}, or @code{c++-mode}.
1016 You probably won't have to set this variable at all; MMM tries to make
1017 intelligent guesses about what modes you prefer. For example, if a
1018 function called @code{javascript-mode} exists, it is chosen, otherwise
1019 @code{c++-mode} is used. Similarly for @code{jde-mode} and
1023 If you do need to change the defaults, you may find the following
1024 function convenient.
1026 @defun mmm-set-major-mode-preferences @var{language} @var{mode} &optional @var{default}
1027 Set the preferred major mode for LANGUAGE to MODE. If there is already
1028 a mode specified for LANGUAGE, and DEFAULT is nil or unsupplied, then it
1029 is changed. If DEFAULT is non-nil, then any existing mode is unchanged.
1030 This is used by packages to ensure that some mode is present, but not
1031 override any user-specified mode. If you are not writing a submode
1032 class, you should ignore the third argument.
1035 Thus, for example, to use @code{my-java-mode} for Java code, you would
1036 use the following line:
1039 (mmm-set-major-mode-preferences 'java 'my-java-mode)
1043 @node Mode Line, Key Bindings, Preferred Modes, Customizing
1044 @comment node-name, next, previous, up
1045 @section Customizing the Mode Line Display
1047 By default, when in a submode region, MMM Mode changes the section of
1048 the mode line (@pxref{Mode Line, , , emacs, The Emacs Manual}) that
1049 normally displays the major mode name---for example, @samp{HTML}---to
1050 instead show both the dominant major mode and the currently active
1051 submode---for example, @samp{HTML[CPerl]}. You can change this format,
1054 @defopt mmm-submode-mode-line-format
1055 The value of this variable should be a string containing one or both of
1056 the escape sequences @samp{~M} and @samp{~m}. The string displayed in
1057 the major mode section of the mode line when in a submode is obtained by
1058 replacing all occurrences of @samp{~M} with the dominant major mode name
1059 and @samp{~m} with the currently active submode name. For example, to
1060 display only the currently active submode, set this variable to
1061 @samp{~m}. The default value is @samp{~M[~m]}.
1064 The MMM minor mode also normally displays the string @samp{MMM} in the
1065 minor mode section of the mode line to indicate when it is active. You
1066 can customize or disable this as well.
1068 @defopt mmm-mode-string
1069 This string is displayed in the minor mode section of the mode line when
1070 the MMM minor mode is active. If nonempty, it should begin with a space
1071 to separate the MMM indicator from that of other minor modes. To
1072 eliminate the indicator entirely, set this variable to the empty string.
1076 @node Key Bindings, Local Variables, Mode Line, Customizing
1077 @comment node-name, next, previous, up
1078 @section Customizing the MMM Mode Key Bindings
1080 The default MMM Mode key bindings are explained in @ref{MMM Mode Keys},
1081 and in @ref{Insertion}. There are a couple of ways to customize these
1084 @defopt mmm-mode-prefix-key
1085 The value of this variable (default is @kbd{C-c %}) should be a key
1086 sequence to use as the prefix for the MMM Mode keymap. Minor modes
1087 typically use @kbd{C-c} followed by a punctuation character, but you can
1088 change it to any user-available key sequence. To have an effect, this
1089 variable should be set before MMM Mode is loaded.
1092 @defopt mmm-use-old-command-keys
1093 When this variable is @code{nil}, MMM Mode commands use the control
1094 modifier and insertion keys no modifier. Any other value switches the
1095 two, so that @code{mmm-parse-buffer}, for example, is bound to @kbd{C-c
1096 % b}, while perl-section insertion in the Mason class is bound to
1097 @kbd{C-c % C-p}. This variable should be set before MMM Mode is loaded
1101 When MMM is loaded, it uses the value of @code{mmm-use-old-command-keys}
1102 to set the values of the variables @code{mmm-command-modifiers} and
1103 @code{mmm-insert-modifiers}, so if you prefer you can set these
1104 variables instead. They should each be a list of key modifiers, such as
1105 @code{(control)} or @code{()}. The Meta modifier is used in some of the
1106 command and insertion keys, so it should not be used, and the Shift
1107 modifier is not particularly portable between Emacsen---if it works for
1108 you, feel free to use it. Other modifiers, such as Hyper and Super, are
1109 not universally available, but are valid when present.
1112 @node Local Variables, Changing Classes, Key Bindings, Customizing
1113 @comment node-name, next, previous, up
1114 @section Changing Saved Local Variables
1116 A lot of the functionality of MMM Mode---that which makes the major mode
1117 appear to change---is implemented by saving and restoring the values of
1118 local variables, or pseudo-variables. You can customize what variables
1119 are saved, and how, with the following variable.
1121 @defvar mmm-save-local-variables
1122 At its simplest, this is a list each of whose elements is a buffer-local
1123 variable whose value is saved and restored for each major mode. Each
1124 elements can also, however, be a list whose first element is the
1125 variable symbol and whose subsequent elements specify how and where the
1126 variable is to be saved. The second element of the list, if present,
1127 should be one of the symbols @code{global}, @code{buffer}, or
1128 @code{region}. If not present, the default value is @code{global}. The
1129 third element, if present, should be a list of major mode symbols in
1130 which to save the variable. In the list form, the variable symbol
1131 itself can be replaced with a cons cell of two functions, one to get the
1132 value and one to set the value. This is called a ``pseudo-variable''.
1135 Globally saved variables are the same in all (MMM-controlled) buffers
1136 and submode regions of each major mode listed in the third argument, or
1137 all major modes if it is @code{t} or not present. Buffer-saved
1138 variables are the same in all submode regions of a given major mode in
1139 each buffer, and region-saved variables can be different for each
1142 Pseudo-variables are used, for example, to save and restore the syntax
1143 table (@pxref{Syntax, , , emacs, The Emacs Manual}) and mode keymaps
1144 (@pxref{Keymaps, , , emacs, The Emacs Manual}).
1147 @node Changing Classes, Hooks, Local Variables, Customizing
1148 @comment node-name, next, previous, up
1149 @section Changing the Supplied Submode Classes
1151 If you need to use MMM with a syntax for which a submode class is not
1152 supplied, and you have some facility with Emacs Lisp, you can write your
1153 own; see @ref{Writing Classes}. However, sometimes you will only want
1154 to make a slight change to one of the supplied submode classes. You can
1155 do this, after that class is loaded, with the following functions.
1157 @defun mmm-set-class-parameter @var{class} @var{param} @var{value}
1158 Set the value of the keyword parameter @var{param} of the submode class
1159 @var{class} to @var{value}. @xref{Writing Classes}, for an explanation
1160 of the meaning of each keyword parameter. This creates a new parameter
1161 if one is not already present in the class.
1164 @defun mmm-get-class-parameter @var{class} @var{param}
1165 Get the value of the keyword parameter @var{param} for the submode class
1166 @var{class}. Returns @code{nil} if there is no such parameter.
1171 @node Hooks, , Changing Classes, Customizing
1172 @comment node-name, next, previous, up
1173 @section Hooks Provided by MMM Mode
1175 MMM Mode defines several hook variables (@pxref{Hooks, , , emacs, The
1176 Emacs Manual}) which are run at different times. The most often used is
1177 @code{mmm-major-mode-hook} which is described in @ref{Major Mode Hook},
1178 but there are a couple others.
1180 @defvar mmm-mode-hook
1181 This normal hook is run whenever MMM Mode is enabled in a buffer.
1184 @defvar mmm-@var{major-mode}-hook
1185 This is actually a whole set of hook variables, a different one for
1186 every major mode. Whenever MMM Mode is enabled in a buffer, the
1187 corresponding hook variable for the dominant major mode is run.
1190 @defvar mmm-@var{submode}-submode-hook
1191 Again, this is a set of one hook variable per major mode. These hooks
1192 are run whenever a submode region of the corresponding major mode is
1193 created in any buffer, with point at the start of the new submode
1197 @defvar mmm-@var{class}-class-hook
1198 This is a set of one hook variable per submode class. These hooks are
1199 run when a submode class is first applied to a given buffer.
1202 Submode classes also have a @code{:creation-hook} parameter which should
1203 be a function to run whenever a submode region is created with that
1204 class, with point at the beginning of the submode region. This can be
1205 set for supplied submode classes with @code{mmm-set-class-parameter};
1206 @ref{Changing Classes}.
1209 @node Supplied Classes, Writing Classes, Customizing, Top
1210 @comment node-name, next, previous, up
1211 @chapter Supplied Submode Classes
1213 This chapter describes the submode classes that are supplied with MMM
1217 * Mason:: Mason server-side Perl in HTML.
1218 * File Variables:: Elisp code in File Variables.
1219 * Here-documents:: Code in shell and Perl here-documents.
1220 * Javascript:: Javascript embedded in HTML.
1221 * Embedded CSS:: CSS Styles embedded in HTML.
1222 * Embperl:: Another syntax for Perl in HTML.
1223 * ePerl:: A general Perl-embedding syntax.
1224 * JSP:: Java code embedded in HTML.
1225 * RPM:: Shell scripts in RPM Spec Files.
1226 * Noweb:: Noweb literate programs.
1229 @node Mason, File Variables, Supplied Classes, Supplied Classes
1230 @comment node-name, next, previous, up
1231 @section Mason: Perl in HTML
1233 Mason is a syntax to embed Perl code in HTML and other documents. See
1234 @uref{http://www.masonhq.com} for more information. The submode class
1235 for Mason components is called `mason' and is loaded on demand from
1236 `mmm-mason.el'. The current Mason class is intended to correctly
1237 recognize all syntax valid in Mason @value{MASON_VERSION}. There are
1238 insertion keys for most of the available syntax; use
1239 @code{mmm-insertion-help} (@kbd{C-c % h} by default) with Mason on to
1242 If you want to have mason submodes automatically in all Mason files, you
1243 can use automatic mode and filename associations; the details depend on
1244 what you call your Mason components and what major mode you use.
1245 @xref{Mode-Ext Classes}. If you use an extension for your Mason files
1246 that emacs does not automatically place in your preferred HTML Mode, you
1247 will probably want to associate that extension with your HTML Mode as
1248 well; @ref{Choosing Modes, , , emacs, The Emacs Manual}. This also goes
1249 for ``special'' Mason files such as autohandlers and dhandlers.
1251 The Perl mode used is controlled by the user: @xref{Preferred Modes}.
1252 The default is to use CPerl mode, if present. Unfortunately, there are
1253 also certain problems with CPerl mode in submode regions. (Not to say
1254 that the original perl-mode would do any better---it hasn't been much
1255 tried.) First of all, the first line of a Perl section is usually
1256 indented as if it were a continuation line. A fix for this is to start
1257 with a semicolon on the first line. The insertion key commands do this
1258 whenever the Mason syntax allows it.
1266 In addition, some users have reported that the CPerl indentation
1267 sometimes does not work. This problem has not yet been tracked down,
1268 however, and more data about when it happens would be helpful.
1270 Some people have reported problems using PSGML with Mason. Adding the
1271 following line to a @file{.emacs} file should suffice to turn PSGML off
1272 and cause emacs to use a simpler HTML mode:
1275 (autoload 'html-mode "sgml-mode" "HTML Mode" t)
1278 Earlier versions of PSGML may require instead the following fix:
1281 (delete '("\\.html$" . sgml-html-mode) auto-mode-alist)
1282 (delete '("\\.shtml$" . sgml-html-mode) auto-mode-alist)
1285 Other users report using PSGML with Mason and MMM Mode without
1286 difficulty. If you don't have problems and want to use PSGML, you may
1287 need to replace @code{html-mode} in the suggested code with
1288 @code{sgml-html-mode}. (Depending on your version of PSGML, this may
1289 not be necessary.) Similarly, if you are using XEmacs and want to use
1290 the alternate HTML mode @code{hm--html-mode}, replace @code{html-mode}
1293 One problem that crops up when using PSGML with Mason is that even
1294 ignoring the special tags and Perl code (which, as I've said, haven't
1295 caused me any problems), Mason components often are not a complete SGML
1296 document. For instance, my autohandlers often say
1304 in which case the actual components contain no doctype declaration,
1305 @code{<html>}, @code{<head>}, or @code{<body>}, confusing PSGML. One
1306 solution I've found is to use the variable @code{sgml-parent-document}
1307 in such incomplete components; try, for example, these lines at the end
1312 %# sgml-parent-document: ("autohandler" "body" nil ("body"))
1313 %# sgml-doctype: "/top/level/autohandler"
1317 This tells PSGML that the current file is a sub-document of the file
1318 @file{autohandler} and is included inside a @code{<body>} tag, thus
1319 alleviating its confusion.
1322 @node File Variables, Here-documents, Mason, Supplied Classes
1323 @comment node-name, next, previous, up
1324 @section Elisp in a Local Variables List
1326 Emacs allows the author of a file to specify major and minor modes to be
1327 used while editing that file, as well as specifying values for other
1328 local Elisp variables, with a File Variables list. @xref{File
1329 Variables, , , emacs, The Emacs Manual}. Since file variables values
1330 are Elisp objects (and with the @code{eval} special ``variable'', they
1331 are forms to be evaluated), one might want to edit them in
1332 @code{emacs-lisp-mode}. The submode class @code{file-variables} allows
1333 this, and is suitable for turning on in a given file with
1334 @code{mmm-classes}, or in all files with @code{mmm-global-classes}.
1337 @node Here-documents, Javascript, File Variables, Supplied Classes
1338 @comment node-name, next, previous, up
1339 @section Here-documents
1341 One of the long-time standard syntaxes for outputting large amounts of
1342 code (or text, or HTML, or whatever) from a script (notably shell
1343 scripts and Perl scripts) is the here-document syntax:
1349 <title>Test Page</title>
1355 The @code{here-doc} submode class recognizes this syntax, and can even
1356 guess the correct submode to use in many cases. For instance, it would
1357 put the above example in @code{html-mode}, noticing the string
1358 @samp{HTML} in the name of the here-document. If you use less than
1359 evocative here-document names, or if the submode is recognized
1360 incorrectly for any other reason, you can tell it explicitly what
1363 @defopt mmm-here-doc-mode-alist
1364 The value of this variable should be an alist, each element a cons pair
1365 associating a regular expression to a submode symbol. Whenever a
1366 here-document name matches one of these regexps, the corresponding
1367 submode is applied. For example, if this variable contains the element
1368 @code{("CODE" . cc-mode)}, then any here-document whose name contains
1369 the string @samp{CODE} will be put in @code{cc-mode}. The value of this
1370 variable overrides any guessing that the @code{here-doc} submode class
1375 @node Javascript, Embedded CSS, Here-documents, Supplied Classes
1376 @comment node-name, next, previous, up
1377 @section Javascript in HTML
1379 The submode class @code{html-js} allows for embedding Javascript code in
1380 HTML documents. It recognizes both this syntax:
1383 <script language="Javascript">
1384 function foo(...) @{
1393 <input type="button" onClick="validate();">
1396 The mode used for Javascript regions is controlled by the user;
1397 @xref{Preferred Modes}.
1400 @node Embedded CSS, Embperl, Javascript, Supplied Classes
1401 @comment node-name, next, previous, up
1402 @section CSS embedded in HTML
1404 CSS (Cascading Style Sheets) can also be embedded in HTML. The
1405 @code{embedded-css} submode class recognizes this syntax:
1415 It uses @code{css-mode} if present, @code{c++-mode} otherwise. This can
1416 be customized: @xref{Preferred Modes}.
1419 @node Embperl, ePerl, Embedded CSS, Supplied Classes
1420 @comment node-name, next, previous, up
1421 @section Embperl: More Perl in HTML
1423 Embperl is another syntax for embedding Perl in HTML. See
1424 @uref{http://perl.apache.org/embperl} for more information. The
1425 @code{embperl} submode class recognizes most if not all of the Embperl
1426 embedding syntax. Its Perl mode is also controllable by the user;
1427 @xref{Preferred Modes}.
1430 @node ePerl, JSP, Embperl, Supplied Classes
1431 @comment node-name, next, previous, up
1432 @section ePerl: General Perl Embedding
1434 Yet another syntax for embedding Perl is called ePerl. See
1435 @uref{http://www.engelschall.com/sw/eperl/} for more information. The
1436 @code{eperl} submode class handles this syntax, using the Perl mode
1437 specified by the user; @xref{Preferred Modes}.
1440 @node JSP, RPM, ePerl, Supplied Classes
1441 @comment node-name, next, previous, up
1442 @section JSP: Java Embedded in HTML
1444 JSP (Java Server Pages) is a syntax for embedding Java code in HTML.
1445 The submode class @code{jsp} handles this syntax, using a Java mode
1446 specified by the user; @xref{Preferred Modes}. The default is
1447 @code{jde-mode} if present, otherwise @code{java-mode}.
1450 @node RPM, Noweb, JSP, Supplied Classes
1451 @comment node-name, next, previous, up
1452 @section RPM Spec Files
1454 @file{mmm-rpm.el} contains the definition of an MMM Mode submode class
1455 for editing shell script sections within RPM (Redhat Package Manager)
1456 spec files. It is recommended for use in combination with
1457 @file{rpm-spec-mode.el} by Stig Bjørlykke <stigb@@tihlde.hist.no> and
1458 Steve Sanbeg <sanbeg@@dset.com>
1459 (@uref{http://www.xemacs.org/~stigb/rpm-spec-mode.el}).
1461 Suggested setup code:
1464 (add-to-list 'mmm-mode-ext-classes-alist
1465 '(rpm-spec-mode "\\.spec\\'" rpm-sh))
1468 Thanks to Marcus Harnisch <Marcus.Harnisch@@gmx.net> for contributing
1471 @node Noweb, , RPM, Supplied Classes
1472 @comment node-name, next, previous, up
1473 @section Noweb literate programming
1475 @file{mmm-noweb.el} contains the definition of an MMM Mode submode
1476 class for editing Noweb documents. Most Noweb documents use \LaTeX
1477 for the documentation chunks. Code chunks in Noweb are
1478 document-specific, and the mode may be set with a local variable
1479 setting in the document. The variable @var{mmm-noweb-code-mode}
1480 controls the global code chunk mode. Since Noweb files may have many
1481 languages in their code chunks, this mode also allows setting the mode
1482 by specifying a mode in the first line or two of a code chunk, using
1483 the normal Emacs first-line mode setting syntax. Note that this
1484 first-line mode setting only matches a single word for the mode name,
1485 and does not support the variable name setting of the generalized
1486 first file line syntax.
1489 % -*- mode: latex; mmm-noweb-code-mode: c++; -*-
1490 % First chunk delimiter!
1492 \noweboptions{smallcode}
1494 \title{Sample Noweb File}
1495 \author{Joe Kelsey\\
1496 \nwanchorto{mailto:bozo@bozo.bozo}{\tt bozo@bozo.bozo}}
1500 \section{Introduction}
1501 Normal noweb documentation for the required [[*]] chunk.
1504 // We might list the program here, or simply included chunks.
1509 \section{[[myfile.cc]]}
1510 This is [[myfile.cc]]. MMM noweb-mode understands code quotes in
1513 // This section is indented separately from previous.
1517 \section{A Perl Chunk}
1518 We need a Perl chunk.
1522 # Each differently named chunk is flowed separately.
1525 \section{Finish [[myfile.cc]]}
1526 When we resume a previously defined chunk, they are indented together.
1528 // Pick up where we left off...
1533 The quoted code chunks inside documentation chunks are given the mode
1534 found in the variable @var{mmm-noweb-quote-mode}, if set, or the value
1535 in @var{mmm-noweb-code-mode} otherwise. Also, each quoted chunk is
1536 set to have a unique name to prevent them from being indented as a
1539 Suggested setup code:
1541 (mmm-add-mode-ext-class 'latex-mode "\\.nw\\'" 'noweb)
1542 (add-to-list 'auto-mode-alist '("\\.nw\\'" . latex-mode))
1545 In mmm-noweb buffers, each differently-named code chunk has a
1546 different @code{:name}, allowing all chunks with the same name to get
1549 This mode also supplies special paragraph filling operations for use
1550 in documentation areas of the buffer. From a primary-mode
1551 (@code{latex-mode, , emacs}) region, pressing @kbd{C-c % C-q} will mark all
1552 submode regions with word syntax (@code{mmm-word-other-regions}), fill
1553 the current paragraph (@code{(fill-paragraph justify)}), and remove the
1554 syntax markings (@code{mmm-undo-syntax-other-regions}).
1556 Thanks to Joe Kelsey <joe@@zircon.seattle.wa.us> for contributing this
1560 @node Writing Classes, Indices, Supplied Classes, Top
1561 @comment node-name, next, previous, up
1562 @chapter Writing Submode Classes
1564 Sometimes (perhaps often) you may want to use MMM with a syntax for
1565 which it is suited, but for which no submode is supplied. In such cases
1566 you may have to write your own submode class. This chapter briefly
1567 describes how to write a submode class, from the basic to the advanced,
1571 * Basic Classes:: Writing a simple submode class.
1572 * Paired Delimiters:: Matching paired delimiters.
1573 * Region Placement:: Placing the region more accurately.
1574 * Submode Groups:: Grouping several classes together.
1575 * Calculated Submodes:: Deciding the submode at run-time.
1576 * Calculated Faces:: Deciding the display face at run-time.
1577 * Insertion Commands:: Inserting regions automatically.
1578 * Region Names:: Naming regions for syntax grouping.
1579 * Other Hooks:: Running code at arbitrary points.
1580 * Delimiters:: Controlling delimiter overlays.
1581 * Misc Keywords:: Other miscellaneous options.
1584 @node Basic Classes, Paired Delimiters, Writing Classes, Writing Classes
1585 @comment node-name, next, previous, up
1586 @section Writing Basic Submode Classes
1587 @cindex simple submode classes
1588 @cindex submode classes, simple
1590 Writing a submode class can become rather complex, if the syntax to
1591 match is complicated and you want to take advantage of some of MMM
1592 Mode's extra features. But a simple submode class is not particularly
1593 difficult to write. This section describes the basics of writing
1596 Submode classes are stored in the variable @code{mmm-classes-alist}.
1597 Each element of this list represents a single submode class. For
1598 convenience, the function @code{mmm-add-classes} takes a list of submode
1599 classes and adds them all to this alist. Each class is represented by a
1600 list containing the class name---a symbol such as @code{mason} or
1601 @code{html-js}---followed by pairs of keywords and arguments called a
1602 @dfn{class specifier}. For example, consider the specifier for the
1603 submode class @code{embedded-css}:
1609 :face mmm-declaration-submode-face
1610 :front "<style[^>]*>"
1614 The name of the submode is @code{embedded-css}, the first element of the
1615 list. The rest of the list consists of pairs of keywords (symbols
1616 beginning with a colon) such as @code{:submode} and @code{:front}, and
1617 arguments, such as @code{css} and @code{"<style[^>]*>"}. It is the
1618 keywords and arguments that specify how the submode works. The order of
1619 keywords is not important; all that matters is the arguments that follow
1622 The three most important keywords are @code{:submode}, @code{:front},
1623 and @code{:back}. The argument following @code{:submode} names the
1624 major mode to use in submode regions. It can be either a symbol naming
1625 a major mode, such as @code{text-mode} or @code{c++-mode}, or a symbol
1626 to look up in @code{mmm-major-mode-preferences} (@pxref{Preferred
1627 Modes}) such as @code{css}, as in this case.
1629 The arguments following @code{:front} and @code{:back} are regular
1630 expressions (@pxref{Regexps, , , emacs, The Emacs Manual}) that should
1631 match the delimiter strings which begin and end the submode regions. In
1632 our example, CSS regions begin with a @samp{<style>} tag, possibly with
1633 parameters, and end with a @samp{</style>} tag.
1635 The argument following @code{:face} specifies the face (background
1636 color) to use when @code{mmm-submode-decoration-level} is 2 (high
1637 coloring). @xref{Region Coloring}, for a list of canonical available
1640 There are many more possible keywords arguments. In the following
1641 sections, we will examine each of them and their uses in writing submode
1645 @node Paired Delimiters, Region Placement, Basic Classes, Writing Classes
1646 @comment node-name, next, previous, up
1647 @section Matching Paired Delimiters
1649 A simple pair of regular expressions does not always suffice to exactly
1650 specify the beginning and end of submode regions correctly. For this
1651 reason, there are several other possible keyword/argument pairs which
1652 influence the matching process.
1654 Many submode regions are marked by paired delimiters. For example, the
1655 tags used by Mason (@pxref{Mason}) include @samp{<%init>...</%init>} and
1656 @samp{<%args>...</%args>}. It would be possible to write a separate
1657 submode class for each type of region, but there is an easier way: the
1658 keyword argument @code{:save-matches}. If supplied and non-nil, it
1659 causes the regular expression @code{:back}, before being searched for,
1660 to be formatted by replacing all strings of the form @samp{~@var{N}}
1661 (where @var{N} is an integer) with the corresponding numbered
1662 subexpression of the match for @code{:front}. As an example, here is an
1663 excerpt from the @code{here-doc} submode class. @xref{Here-documents},
1664 for more information about this submode.
1667 :front "<<\\([a-zA-Z0-9_-]+\\)"
1672 The regular expression for @code{:front} matches @samp{<<} followed by a
1673 string of one or more alphanumeric characters, underscores, and dashes.
1674 The latter string, which happens to be the name of the here-document, is
1675 saved as the first subexpression, since it is surrounded by
1676 @samp{\(...\)}. Then, because the value of @code{:save-matches} is
1677 present and non-nil, the string @samp{~1} is replaced in the value of
1678 @code{:back} by the name of the here-document, thus creating a regular
1679 expression to match the correct ending delimiter.
1682 @node Region Placement, Submode Groups, Paired Delimiters, Writing Classes
1683 @comment node-name, next, previous, up
1684 @section Placing Submode Regions Precisely
1686 Normally, a submode region begins immediately after the end of the
1687 string matching the @code{:front} regular expression and ends
1688 immediately before the beginning of the string matching the @code{:back}
1689 regular expression. This can be changed with the keywords
1690 @code{:include-front} and @code{:include-back}. If their arguments are
1691 @code{nil}, or they do not appear, the default behavior is unchanged.
1692 But if the argument of @code{:include-front} (respectively,
1693 @code{:include-back}) is non-nil, the submode region will begin
1694 (respectively, end) immediately before (respectively, after) the string
1695 matching the @code{:front} (respectively, @code{:back}) regular
1696 expression. In other words, these keywords specify whether or not the
1697 delimiter strings are @emph{included} in the submode region.
1699 When @code{:front} and @code{:back} are regexps, the delimiter is
1700 normally considered to be the entire matched region. This can be
1701 changed using the @code{:front-match} and @code{:back-match}
1702 keywords. The values of the keywords is a number specifying the
1703 submatch. This defaults to zero (specifying the whole regexp).
1705 Two more keywords which affect the placement of the region
1706 @code{:front-offset} and @code{:back-offset}, which both take integers
1707 as arguments. The argument of @code{:front-offset} (respectively,
1708 @code{:back-offset}) gives the distance in characters from the beginning
1709 (respectively, ending) location specified so far, to the actual point
1710 where the submode region begins (respectively, ends). For example, if
1711 @code{:include-front} is nil or unsupplied and @code{:front-offset} is
1712 2, the submode region will begin two characters after the end of the
1713 match for @code{:front}, and if @code{:include-back} is non-nil and
1714 @code{:back-offset} is -1, the region will end one character before the
1715 end of the match for @code{:back}.
1717 In addition to integers, the arguments of @code{:front-offset} and
1718 @code{:back-offset} can be functions which are invoked to move the point
1719 from the position specified by the matches and inclusions to the correct
1720 beginning or end of the submode region, or lists whose elements are
1721 either functions or numbers and whose effects are applied in sequence.
1722 To help disentangle these options, here is another excerpt from the
1723 @code{here-doc} submode class:
1726 :front "<<\\([a-zA-Z0-9_-]+\\)"
1727 :front-offset (end-of-line 1)
1732 Here the value of @code{:front-offset} is the list @code{(end-of-line
1733 1)}, meaning that from the end of the match for @code{:front}, go to the
1734 end of the line, and then one more character forward (thus to the
1735 beginning of the next line), and begin the submode region there. This
1736 coincides with the normal behavior of here-documents: they begin on the
1737 following line and go until the ending flag.
1739 If the @code{:back} should not be able to start a new submode region,
1740 set the @code{:end-not-begin} keyword to non-nil.
1742 @node Submode Groups, Calculated Submodes, Region Placement, Writing Classes
1743 @comment node-name, next, previous, up
1744 @section Defining Groups of Submodes
1746 Sometimes more than one submode class is required to accurately reflect
1747 the behavior of a single type of syntax. For example, Mason has three
1748 very different types of Perl regions: blocks bounded by matched tags
1749 such as @samp{<%perl>...</%perl>}, inline output expressions bounded by
1750 @samp{<%...%>}, and single lines of code which simply begin with a
1751 @samp{%} character. In cases like these, it is possible to specify an
1752 ``umbrella'' class, to turn all these classes on or off together.
1754 @defun mmm-add-group @var{group} @var{classes}
1755 The submode classes @var{classes}, which should be a list of lists,
1756 similar to what might be passed to @code{mmm-add-classes}, are added
1757 just as by that function. Furthermore, another class named
1758 @var{group} is added, which encompasses all the classes in
1762 Technically, an group class is specified with a @code{:classes} keyword
1763 argument, and the subsidiary classes are given a non-nil @code{:private}
1764 keyword argument to make them invisible. But in general, all you should
1765 ever need to know is how to invoke the function above.
1767 @defun mmm-add-to-group @var{group} @var{classes}
1768 Adds a list of classes to an already existing group. This can be
1769 used, for instance, to add a new quoting definition to @var{html-js}
1770 using this example to add the quote characters ``%=%'':
1773 (mmm-add-to-group 'html-js '((js-html
1775 :face mmm-code-submode-face
1783 @node Calculated Submodes, Calculated Faces, Submode Groups, Writing Classes
1784 @comment node-name, next, previous, up
1785 @section Calculating the Correct Submode
1787 In most cases, the author of a submode class will know in advance what
1788 major mode to use, such as @code{text-mode} or @code{c++-mode}. If
1789 there are multiple possible modes that the user might desire, then
1790 @code{mmm-major-mode-preferences} should be used (@pxref{Preferred
1791 Modes}). The function @code{mmm-set-major-mode-preferences} can be
1792 used, with a third argument, to ensure than the mode is present.
1794 In some cases, however, the author has no way of knowing in advance even
1795 what language the submode region will be in. The @code{here-doc} class
1796 is one of these. In such cases, instead of the @code{:submode} keyword,
1797 the @code{:match-submode} keyword must be used. Its argument should be
1798 a function, probably written by the author of the submode class, which
1799 calculates what major mode each region should use.
1801 It is invoked immediately after a match is found for @code{:front}, and
1802 is passed one argument: a string representing the front delimiter.
1803 Normally this string is simply whatever was matched by @code{:front},
1804 but this can be changed with the keyword @code{:front-form}
1805 (@pxref{Delimiters}). The function should then return a symbol
1806 that would be a valid argument to @code{:submode}: either the name of a
1807 mode, or that of a language to look up a preferred mode. If it detects
1808 an invalid match---for example, the user has specified a mode which is
1809 not available---it should @code{(signal 'mmm-no-matching-submode nil)}.
1811 Since here-documents can contain code in any language, the
1812 @code{here-doc} submode class uses @code{:match-submode} rather than
1813 @code{:submode}. The function it uses is @code{mmm-here-doc-get-mode},
1814 defined in @file{mmm-sample.el}, which inspects the name of the
1815 here-document for flags indicating the proper mode. For example, this
1816 code should probably be in @code{perl-mode} (or @code{cperl-mode}):
1824 This function is also a good example of proper elisp hygiene: when
1825 writing accessory functions for a submode class, they should usually be
1826 prefixed with @samp{mmm-} followed by the name of the submode class, to
1827 avoid namespace conflicts.
1830 @node Calculated Faces, Insertion Commands, Calculated Submodes, Writing Classes
1831 @comment node-name, next, previous, up
1832 @section Calculating the Correct Highlight Face
1834 As explained in @ref{Basic Classes}, the keyword @code{:face} should be
1835 used to specify which of the standard submode faces (@pxref{Region
1836 Coloring}) a submode region should be highlighted with under high
1837 decoration. However, sometimes the function of a region can depend on
1838 the form of the delimiters as well. In this case, a more flexible
1839 alternative to @code{:face} is @code{:match-face}. Its value can be a
1840 function, which is called with one argument---the form of the front
1841 delimiter, as with @code{:match-submode}---and should return the face to
1842 use. A more common value for @code{:match-face} is an association list,
1843 a list of pairs @code{(@var{delim} . @var{face})}, each specifying that
1844 if the delimiter is @var{delim}, the corresponding region should be
1845 highlighted with @var{face}. For example, here is an excerpt from the
1846 @code{embperl} submode class:
1850 :front "\\[\\([-\\+!\\*\\$]\\)"
1853 :match-face (("[+" . mmm-output-submode-face)
1854 ("[-" . mmm-code-submode-face)
1855 ("[!" . mmm-init-submode-face)
1856 ("[*" . mmm-code-submode-face)
1857 ("[$" . mmm-special-submode-face))
1860 Thus, regions beginning with @samp{[+} are highlighted as output
1861 expressions, which they are, while @samp{[-} and @samp{[*} regions are
1862 highlighted as simple executed code, and so on. Note that
1863 @var{mmm-submode-decoration-level} must be set to 2 (high decoration)
1864 for different faces to be displayed.
1867 @node Insertion Commands, Region Names, Calculated Faces, Writing Classes
1868 @comment node-name, next, previous, up
1869 @section Specifying Insertion Commands
1871 As described in @ref{Insertion}, submode classes can specify key
1872 sequences which automatically insert submode regions, with delimiters
1873 already in place. This is done by the keyword argument @code{:insert}.
1874 Its value should be a list, each element of which specifies a single
1875 insertion key sequence. As an example, consider the following insertion
1876 key sequence specifier, from the @code{embperl} submode class:
1879 (?p embperl "Region Type (Character): "
1880 @@ "[" str @@ " " _ " " @@ str "]" @@)
1883 As you can see, the specifier is a list. The first element of the list
1884 is the character @samp{p}. (The question mark tells Emacs that this is
1885 a character object, not a one-character symbol.) In general, the first
1886 element can be any key, including both characters such as @samp{?p} and
1887 function keys such as @samp{return}. It can also be a dotted pair in
1888 which the first element is a modifier symbol such as @code{meta}, and
1889 the second is a character or function key. The use of any other
1890 modifier than meta is discouraged, as `mmm-insert-modifiers' is
1891 sometimes set to \(control), and other modifiers are not very portable.
1892 The second element is a symbol identifying this key sequence. The third
1893 element is a prompt string which is used to ask the user for input when
1894 this key sequence is invoked. If it is nil, the user is not prompted.
1896 The rest of the list specifies the actual text to be inserted, where the
1897 submode region and delimiters should be, and where the point should end
1898 up. (Actually, this string is simply passed to @code{skeleton-insert};
1899 see the documentation string of that function for more details on the
1900 permissible elements of such a skeleton.) Strings and variable names
1901 are inserted and interpolated. The value entered by the user when
1902 prompted, if any, is available in the variable @code{str}. The final
1903 location of the point (or the text around which the region is to be
1904 wrapped) is marked with a single underscore @samp{_}. Finally, the
1905 @@-signs mark the delimiters and submode regions. There should be four
1906 @@-signs: one at the beginning of the front delimiter, one at the
1907 beginning of the submode region, one at the end of the submode region,
1908 and one at the end of the back delimiter.
1910 The above key sequence, bound by default to @kbd{C-c % p}, always
1911 prompts the user for the type of region to insert. It can also be
1912 convenient to have separate key sequences for each type of region to be
1913 inserted, such as @kbd{C-c % +} for @samp{[+...+]} regions, @kbd{C-c %
1914 -} for @samp{[-...-]} regions, and so on. So that the whole skeleton
1915 doesn't have to be written out half a dozen times, there is a shortcut
1919 (?+ embperl+ ?p . "+")
1922 If the key sequence specification is a dotted list with four elements,
1923 as this example is, it means to use the skeleton defined for the key
1924 sequence given as the third element (@code{?p}), but to pass it the
1925 fourth (dotted) element (@code{"+"}) as the `str' variable; the user is
1929 @node Region Names, Other Hooks, Insertion Commands, Writing Classes
1930 @comment node-name, next, previous, up
1931 @section Giving Names to Submode Regions for Grouping
1933 Submode regions can be given ``names'' which are used for grouping.
1934 Names are always strings and are compared as strings. Regions with
1935 the same name are considered part of the same chunk of code. This is
1936 used by the syntax and fontification functions. Unnamed regions are
1937 not grouped with any others.
1939 By default, regions are nameless, but with the @code{:match-name}
1940 keyword argument a name can be supplied. This argument must be a
1941 string or a function. If it is a function, it is passed a string
1942 representing the front delimiter found, and must return the name to
1943 use. If it is a string, it is used as-is for the name, unless
1944 @code{:save-name} has a non-nil value, in which case expressions such
1945 as @samp{~1} are substituted with the corresponding matched
1946 subexpression from @code{:front}. This is the same as how
1947 @code{:back} is interpreted when @code{:save-matches} is non-nil.
1949 As a special optimization for region insertion (@pxref{Insertion
1950 Commands}), the argument @code{:skel-name} can be set to a non-nil
1951 value, in which case the insertion code will use the user-prompted
1952 string value as the region name, instead of going through the normal
1956 @node Other Hooks, Delimiters, Region Names, Writing Classes
1957 @comment node-name, next, previous, up
1958 @section Other Hooks into the Scanning Process
1960 Sometimes, even the flexibility allowed by all the keyword arguments
1961 discussed so far is insufficient to correctly match submode regions.
1962 There are several other keyword arguments which accept custom functions
1963 to be invoked at various points in the MMM-ification process.
1965 First of all, the arguments of @code{:front} and @code{:back}, in
1966 addition to regular expressions, can be themselves functions. Such
1967 functions should ``act like'' a regular expression search: they should
1968 start searching at point, take one argument as a limit for the search,
1969 and return its result by setting the match data (presumably by calling
1970 some regexp matching function).
1972 This is rarely necessary, however, because often all that is needed is a
1973 simple regexp search, followed by some sort of verification. The
1974 keyword arguments @code{:front-verify} and @code{:back-verify}, if
1975 supplied, may be functions which are invoked after a match is found for
1976 @code{:front} or @code{:back}, respectively, and should inspect the
1977 match data (such as with @code{match-string}) and return non-nil if a
1978 submode region should be begun at this match, nil if this match should
1979 be ignored and the search continue after it.
1981 The keyword argument @code{:creation-hook}, if supplied, should be a
1982 function that is invoked whenever a submode region of this class is
1983 created, with point at the beginning of the new region. This can be
1984 used, for example, to set local variables appropriately.
1986 Finally, the entire MMM-ification process has a ``back door'' which
1987 allows class authors to take control of the entire thing. If the
1988 keyword argument @code{:handler} is supplied, it overrides any other
1989 processing and is called, and passed all other class keyword arguments,
1990 instead of @code{mmm-ify} to create submode regions. If you need to
1991 write a handler function, I suggest looking at the source for
1992 @code{mmm-ify} to get an idea of what must be done.
1995 @node Delimiters, Misc Keywords, Other Hooks, Writing Classes
1996 @comment node-name, next, previous, up
1997 @section Controlling the Delimiter Regions and Forms
1999 MMM also makes overlays for the delimiter regions, to keep track of
2000 their position and form. Normally, the front delimiter overlay starts
2001 at the beginning of the match for @code{:front} and ends at the
2002 beginning of the submode region overlay, while the back delimiter
2003 overlay starts at the end of the submode region overlay and ends at
2004 the end of the match for @code{:back}. You can supply offsets from
2005 these positions using the keyword arguments @code{:front-delim} and
2006 @code{:back-delim}, which take values of the same sort as
2007 @code{:front-offset} and @code{:back-offset}.
2009 In addition, the delimiter regions can be in a major mode of their
2010 own. There are usually only two meaningful modes to use: the primary
2011 mode or a non-mode like fundamental-mode. These correspond to the
2012 following two situations:
2016 If the delimiter syntax which specifies the submode regions is
2017 something @emph{added to} the syntax of the primary mode by a
2018 pre-interpreter, then the delimiter regions should be in a non-mode.
2019 This is the case, for example, with all server-side HTML script
2020 extensions, such as @xref{Mason}, @xref{Embperl}, and @xref{ePerl}.
2021 It is also the case for literate programming such as @xref{Noweb}.
2022 This is the default behavior. The non-mode used is controlled by the
2023 variable @code{mmm-delimiter-mode}, which defaults to
2027 If, on the other hand, the delimiter syntax and inclusion of different
2028 modes is an @emph{intrinsic part} of the primary mode, then the
2029 delimiter regions should remain in the primary mode. This is the
2030 case, for example, with @xref{Embedded CSS}, and @xref{Javascript},
2031 since the @code{<style>} and @code{<script>} tags are perfectly valid
2032 HTML. In this case, you should give the keyword parameter
2033 @code{:delimiter-mode} with a value of @code{nil}, meaning to use the
2037 The keyword parameter @code{:delimiter-mode} can be given any major
2038 mode as an argument, but the above two situations should cover the
2039 vast majority of cases.
2041 The delimiter regions can also be highlighted, if you wish. The
2042 keyword parameters @code{:front-face} and @code{:back-face} may be
2043 faces specifying how to highlight these regions under high
2044 decoration. Under low decoration, the value of the variable
2045 @code{mmm-delimiter-face} is used (by default, nothing), and of course
2046 under no decoration there is no coloring.
2048 Finally, for each submode region overlay, MMM Mode stores the ``form''
2049 of the front and back delimiters, which are regular expressions that
2050 match the delimiters. At present these are not used for much, but in
2051 the future they may be used to help with automatic updating of regions
2052 as you type. Normally, the form stored is the result of evaluating
2053 the expression @code{(regexp-quote (match-string 0))} after each match
2056 You can customize this with the keyword argument @code{:front-form}
2057 (respectively, @code{:back-form}). If it is a string, it is used
2058 verbatim for the front (respectively, back) form. If it is a function,
2059 that function is called and should inspect the match data and return the
2060 regular expression to use as the form.
2062 In addition, the form itself can be set to a function, by giving a
2063 one-element list containing only that function as the argument to
2064 @code{:front-form} or @code{:back-form}. Such a function should take
2065 1-2 arguments. The first argument is the overlay to match the delimiter
2066 for. If the second is non-nil, it means to insert the delimiter and
2067 adjust the overlay; if nil it means to match the delimiter and return
2068 the result in the match data.
2071 @node Misc Keywords, , Delimiters, Writing Classes
2072 @comment node-name, next, previous, up
2073 @section Miscellaneous Other Keyword Arguments
2075 You can specify whether delimiter searches should be case-sensitive with
2076 the keyword argument @code{:case-fold-search}. It defaults to @code{t},
2077 meaning that case should be ignored. See the documentation for the
2078 variable @code{case-fold-search}.
2080 @node Indices, , Writing Classes, Top
2081 @comment node-name, next, previous, up
2085 * Concept Index:: Index of MMM Mode Concepts.
2086 * Function Index:: Index of functions and variables.
2087 * Keystroke Index:: Index of key bindings in MMM Mode.
2090 @node Concept Index, Function Index, Indices, Indices
2091 @comment node-name, next, previous, up
2092 @section Concept Index
2097 @node Function Index, Keystroke Index, Concept Index, Indices
2098 @comment node-name, next, previous, up
2099 @section Function and Variable Index
2104 @node Keystroke Index, , Function Index, Indices
2105 @comment node-name, next, previous, up
2106 @section Keystroke Index
2116 @c mode: outline-minor