1 This is mmm.info, produced by makeinfo version 4.2 from mmm.texinfo.
3 INFO-DIR-SECTION GNU Emacs Lisp
5 * MMM-Mode: (mmm). Multiple Major Modes for Emacs
8 This is edition 0.4.8 of the MMM Mode Manual, last updated 9 March
9 2003. It documents version 0.4.8 of MMM Mode.
11 Copyright 2000 Michael Abraham Shulman.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
17 Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided also
19 that the sections entitled "Copying" and "GNU General Public License"
20 are included exactly as in the original, and provided that the entire
21 resulting derived work is distributed under the terms of a permission
22 notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that this permission notice may be stated in a
27 translation approved by the Free Software Foundation.
30 File: mmm.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
35 MMM Mode is a minor mode for Emacs which allows Multiple Major Modes
36 to coexist in a single buffer.
38 This is edition 0.4.8 of the MMM Mode Manual, last updated 9 March
39 2003, which documents version 0.4.8 of MMM Mode.
43 * Overview:: An overview and introduction to MMM Mode.
44 * Basics:: The basics of how to use it.
45 * Customizing:: Customizing how it works to your needs.
46 * Supplied Classes:: The supplied submode classes.
47 * Writing Classes:: Writing your own submode classes.
48 * Indices:: Just that.
50 --- The Detailed Node Listing ---
54 * Basic Concepts:: A simple explanation of how it works.
55 * Installation:: How to install MMM Mode.
56 * Quick Start:: Getting started using MMM Mode quickly.
60 * MMM Minor Mode:: The Emacs minor mode that manages it all.
61 * Submode Classes:: What they are and how to use them.
62 * Selecting Classes:: How MMM Mode knows what classes to use.
63 * Insertion:: Inserting new submode regions automatically.
64 * Re-parsing:: Re-scanning for submode regions.
65 * Interactive:: Adding submode regions manually.
66 * Global Mode:: Turning MMM Mode on automatically.
70 * Enabling MMM Mode:: Turning MMM Mode on and off.
71 * MMM Mode Keys:: Default key bindings in MMM Mode.
73 How MMM Mode selects submode classes
75 * File Classes:: Classes for a single file.
76 * Mode-Ext Classes:: Classes for a given mode or extension.
77 * Global Classes:: Classes for all MMM Mode buffers.
81 * Major Mode Hook:: Using MMM's Major Mode Hook
85 * Region Coloring:: Changing or removing background colors.
86 * Preferred Modes:: Choosing which major modes to use.
87 * Mode Line:: What is displayed in the mode line.
88 * Key Bindings:: Customizing the MMM Mode key bindings.
89 * Local Variables:: What local variables are saved for submodes.
90 * Changing Classes:: Changing the supplied submode classes.
91 * Hooks:: How to make MMM Mode run your code.
93 Supplied Submode Classes
95 * Mason:: Mason server-side Perl in HTML.
96 * File Variables:: Elisp code in File Variables.
97 * Here-documents:: Code in shell and Perl here-documents.
98 * Javascript:: Javascript embedded in HTML.
99 * Embedded CSS:: CSS Styles embedded in HTML.
100 * Embperl:: Another syntax for Perl in HTML.
101 * ePerl:: A general Perl-embedding syntax.
102 * JSP:: Java code embedded in HTML.
103 * RPM:: Shell scripts in RPM Spec Files.
104 * Noweb:: Noweb literate programs.
106 Writing Submode Classes
108 * Basic Classes:: Writing a simple submode class.
109 * Paired Delimiters:: Matching paired delimiters.
110 * Region Placement:: Placing the region more accurately.
111 * Submode Groups:: Grouping several classes together.
112 * Calculated Submodes:: Deciding the submode at run-time.
113 * Calculated Faces:: Deciding the display face at run-time.
114 * Insertion Commands:: Inserting regions automatically.
115 * Region Names:: Naming regions for syntax grouping.
116 * Other Hooks:: Running code at arbitrary points.
117 * Delimiters:: Controlling delimiter overlays.
118 * Misc Keywords:: Other miscellaneous options.
122 * Concept Index:: Index of MMM Mode Concepts.
123 * Function Index:: Index of functions and variables.
124 * Keystroke Index:: Index of key bindings in MMM Mode.
127 File: mmm.info, Node: Overview, Next: Basics, Prev: Top, Up: Top
132 MMM Mode is a minor mode for Emacs which allows Multiple Major Modes
133 to coexist in a single buffer. The name is an abbreviation of `Multiple
134 Major Modes'(1). A major mode is a customization of Emacs for editing a
135 certain type of text, such as code for a specific programming language.
136 *Note Major Modes: (emacs)Major Modes, for details.
138 MMM Mode is a general extension to Emacs which is useful whenever one
139 file contains text in two or more programming languages, or that should
140 be in two or more different modes. For example:
142 * CGI scripts written in any language, from Perl to PL/SQL, may want
143 to output verbatim HTML, and the writer of such scripts may want
144 to use Emacs' html-mode or sgml-mode to edit this HTML code, while
145 remaining in the appropriate programming language mode for the
146 rest of the file. *Note Here-documents::, for example.
148 * There are now many "content delivery systems" which turn the CGI
149 script idea around and simply add extra commands to an HTML file,
150 often in some programming language, which are interpreted on the
151 server. *Note Mason::, *Note Embperl::, *Note ePerl::, *Note
154 * HTML itself can also contain embedded languages such as Javascript
155 and CSS styles, for which Emacs has different major modes. *Note
156 Javascript::, and *Note Embedded CSS::, for example.
158 * The idea of "literate programming" requires the same file to
159 contain documentation (written as text, html, latex, etc.) and
160 code (in an appropriate programming language). *Note Noweb::, for
163 * Emacs allows files of any type to contain `local variables', which
164 can include Emacs Lisp code to be evaluated. *Note File Variables:
165 (emacs)File Variables. It may be easier to edit this code in Emacs
166 Lisp mode than in whatever mode is used for the rest of the file.
167 *Note File Variables::.
169 * There are many more possible uses for MMM Mode. RPM spec files can
170 contain shell scripts (*note RPM::). Email or newsgroup messages
171 may contain sample code. And so on. We encourage you to
176 * Basic Concepts:: A simple explanation of how it works.
177 * Installation:: How to install MMM Mode.
178 * Quick Start:: Getting started using MMM Mode quickly.
180 ---------- Footnotes ----------
182 (1) The name is derived from `mmm.el' for XEmacs by Gongquan Chen
183 <chen@posc.org>, from which MMM Mode was adapted.
186 File: mmm.info, Node: Basic Concepts, Next: Installation, Prev: Overview, Up: Overview
191 The way MMM Mode works is as follows. Each buffer has a "dominant"
192 or "default" major mode, which is chosen as major modes normally are:
193 the user can set it interactively, or it can be chosen automatically
194 with `auto-mode-alist' (*note Choosing Modes: (emacs)Choosing Modes.).
195 Within the file, MMM Mode creates "submode regions" within which other
196 major modes are in effect. While the point is in a submode region, the
197 following changes occur:
199 1. The local keymap is that of the submode. This means the key
200 bindings for the submode are available, while those of the
201 dominant mode are not.
203 2. The mode line (*note Mode Line: (emacs)Mode Line.) changes to show
204 which submode region is active. This can be configured; see *Note
207 3. The major mode menu, both on the menu bar and the mouse popup, are
210 4. Some local variables of the submode shadow those of the default
211 mode (*note Local Variables::). For the user, this serves to help
212 make Emacs behave as if the submode were the major mode.
214 5. The syntax table and indentation are those of the submode.
216 6. Font-lock (*note Font Lock: (emacs)Font Lock.) fontifies correctly
219 7. The submode regions are highlighted by a background color; see
220 *Note Region Coloring::.
223 The submode regions are represented internally by Emacs Lisp objects
224 known as "overlays". Some of the above are implemented by overlay
225 properties, and others are updated by an MMM Mode function in
226 `post-command-hook'. You don't need to know this to use MMM Mode, but it
227 may make any error messages you come across more understandable. *Note
228 Overlays: (elisp)Overlays, for more information on overlays.
230 Because overlays are not saved with a file, every time a file is
231 opened, they must be created. Creating submode regions is occasionally
232 referred to as "mmm-ification". (I've never had occasion to pronounce
233 this, but if I did I would probably say `mummification'. Like what they
234 did in ancient Egypt.) You can mmm-ify a buffer interactively, but
235 most often MMM Mode will find and create submode regions automatically
236 based on a buffer's file extension, dominant mode, or local variables.
239 File: mmm.info, Node: Installation, Next: Quick Start, Prev: Basic Concepts, Up: Overview
244 MMM Mode has a standard installation process. See the file INSTALL
245 for generic information on this process. To summarize, unpack the
246 archive, `cd' to the created MMM Mode directory, type `./configure',
247 then `make', then `make install'. If all goes correctly, this will
248 compile the MMM Mode elisp files, install them in your local site-lisp
249 directory, and install the MMM Mode info file `mmm.info' in your local
252 Now you need to configure your Emacs initialization file (usually
253 `~/.emacs') to use MMM Mode. First, Emacs has to know where to find
254 MMM Mode. In other words, the MMM Mode directory has to be in
255 `load-path'. This can be done in the parent directory's `subdirs.el'
256 file, or in the init file with a line such as:
258 (add-to-list 'load-path "/path/to/site-lisp/mmm/")
260 Once `load-path' is configured, MMM Mode must be loaded. You can
261 load all of MMM Mode with the line
265 but if you use MMM Mode only rarely, it may not be desirable to load all
266 of it at the beginning of every editing session. You can load just
267 enough of MMM Mode so it will turn itself on when necessary and load the
268 rest of itself, by using instead the line
272 in your initialization file.
274 One more thing you may want to do right now is to set the variable
275 `mmm-global-mode'. If this variable is `nil' (the default), MMM Mode
276 will never turn itself on. If it is `t', MMM Mode will turn itself on
277 in every buffer. Probably the most useful value for it, however, is
278 the symbol `maybe' (actually, anything that is not `nil' and not `t'),
279 which causes MMM Mode to turn itself on in precisely those buffers
280 where it would be useful. You can do this with a line such as:
282 (setq mmm-global-mode 'maybe)
284 in your initialization file. *Note Global Mode::, for more detailed
288 File: mmm.info, Node: Quick Start, Prev: Installation, Up: Overview
290 Getting Started Quickly
291 =======================
293 Perhaps the simplest way to create submode regions is to do it
294 interactively by specifying a region. First you must turn MMM Mode
295 on--say, with `M-x mmm-mode'--then place point and mark around the area
296 you want to make into a submode region, type `C-c % C-r', and enter the
297 desired major mode. *Note Interactive::, for more details.
299 A better way to add submode regions is by using submode classes,
300 which store a lot of useful information for MMM Mode about how to add
301 and manipulate the regions created. *Note Submode Classes::, for more
302 details. There are several sample submode classes that come with MMM
303 Mode, which are documented later in this manual. Look through these and
304 determine if one of them fits your needs. If so, I suggest reading the
305 comments on that mode. Then come back here to find out to use it.
307 To apply a submode class to a buffer interactively, turn MMM Mode on
308 as above, then type `C-c % C-c' and enter the name of the class.
309 Submode regions should be added automatically, if there are any regions
310 in the buffer appropriate to the submode class.
312 If you want a given file to always use a given submode class, you can
313 express this in a file variable: add a line containing the string `-*-
314 mmm-classes: CLASS -*-' at the top of the file. *Note File Variables:
315 (emacs)File Variables, for more information and other methods. Now
316 whenever MMM Mode is turned on in that file, it will be mmm-ified
317 according to CLASS. If `mmm-global-mode' is non-nil, then MMM Mode will
318 turn itself on whenever a file with a `mmm-classes' local variable is
319 opened. *Note Global Mode::, for more information.
321 If you want a submode class to apply to _all_ files in a certain
322 major mode or with a certain extension, add a line such as this to your
325 (mmm-add-mode-ext-class MODE EXTENSION CLASS)
327 After this call, any file opened whose name matches the regular
328 expression EXTENSION _and_ whose default mode is MODE will be
329 automatically mmm-ified according to CLASS (assuming `mmm-global-mode'
330 is non-nil). If one of EXTENSION or MODE is `nil', a file need only
331 satisfy the other one to be mmm-ified.
333 You can now read the rest of this manual to learn more about how MMM
334 Mode works and how to configure it to your preferences. If none of the
335 supplied submode classes fit your needs, then you can try to write your
336 own. *Note Writing Classes::, for more information.
339 File: mmm.info, Node: Basics, Next: Customizing, Prev: Overview, Up: Top
344 This chapter explains the most important parts of how to use MMM
349 * MMM Minor Mode:: The Emacs minor mode that manages it all.
350 * Submode Classes:: What they are and how to use them.
351 * Selecting Classes:: How MMM Mode knows what classes to use.
352 * Insertion:: Inserting new submode regions automatically.
353 * Re-parsing:: Re-scanning for submode regions.
354 * Interactive:: Adding submode regions manually.
355 * Global Mode:: Turning MMM Mode on automatically.
358 File: mmm.info, Node: MMM Minor Mode, Next: Submode Classes, Prev: Basics, Up: Basics
363 An Emacs minor mode is an optional feature which can be turned on or
364 off in a given buffer, independently of the major mode. *Note Minor
365 Modes: (emacs)Minor Modes. MMM Mode is implemented as a minor mode
366 which manages the submode regions. This minor mode must be turned on in
367 a buffer for submode regions to be effective. When activated, the MMM
368 Minor mode is denoted by `MMM' in the mode line (*note Mode Line::).
372 * Enabling MMM Mode:: Turning MMM Mode on and off.
373 * MMM Mode Keys:: Default key bindings in MMM Mode.
376 File: mmm.info, Node: Enabling MMM Mode, Next: MMM Mode Keys, Prev: MMM Minor Mode, Up: MMM Minor Mode
381 If `mmm-global-mode' is non-`nil' (*note Global Mode::), then the
382 MMM minor mode will be turned on automatically whenever a file with
383 associated submode classes is opened (*note Selecting Classes::). It
384 is also turned on by interactive mmm-ification (*note Interactive::),
385 although the interactive commands do not have key bindings when it is
386 not on and must be invoked via `M-x'. You can also turn it on (or off)
387 manually with `M-x mmm-mode', in which case it applies all submode
388 classes associated with the buffer. Turning MMM Mode off automatically
389 removes all submode regions from the buffer.
391 - Command: mmm-mode ARG
392 Toggle the state of MMM Mode in the current buffer. If ARG is
393 supplied, turn MMM Mode on if and only if ARG is positive.
395 - Function: mmm-mode-on
396 Turn MMM Mode on unconditionally in the current buffer.
398 - Function: mmm-mode-off
399 Turn MMM Mode off unconditionally in the current buffer.
402 This variable represents whether MMM Mode is on in the current
403 buffer. Do not set this variable directly; use one of the above
407 File: mmm.info, Node: MMM Mode Keys, Prev: Enabling MMM Mode, Up: MMM Minor Mode
409 Key Bindings in MMM Mode
410 ------------------------
412 When MMM Mode is on, it defines a number of key bindings. By default,
413 these are bound after the prefix sequence `C-c %'. Minor mode keymaps
414 are supposed to use `C-c PUNCTUATION' sequences, and I find this one to
415 be a good mnemonic because `%' is used by Mason to denote special tags.
416 This prefix key can be customized; *Note Key Bindings::.
418 There are two types of key bindings in MMM Mode: "commands" and
419 "insertions". Command bindings run MMM Mode interactive functions to do
420 things like re-parse the buffer or end the current submode region, and
421 are defined statically as normal Emacs key-bindings. Insertion bindings
422 insert submode region skeletons with delimiters into the buffer, and
423 are defined dynamically, according to which submode classes (*note
424 Submode Classes::) are in effect, via a keymap default binding.
426 To distinguish between the two, MMM Mode uses distinct modifier keys
427 for each. By default, command bindings use the control key (e.g. `C-c %
428 C-b' re-parses the buffer), and insertion bindings do not (e.g. `C-c %
429 p', when the Mason class is in effect, inserts a `<%perl>...</%perl>'
430 region). This makes the command bindings different from in previous
431 versions, however, so the variable `mmm-use-old-bindings' is provided.
432 If this variable is set to `t' before MMM Mode is loaded, the bindings
433 will be reversed: insertion bindings will use the control key and
434 command bindings will not.
436 Normally, Emacs gives help on a prefix command if you type `C-h'
437 after that command (e.g. `C-x C-h' displays all key bindings starting
438 with `C-x'). Because of how insertion bindings are implemented
439 dynamically with a default binding, they do not show up when you hit
440 `C-c % C-h'. For this reason, MMM Mode defines the command `C-c % h'
441 which displays a list of all currently valid insertion key sequences.
442 If you use the defaults for command and insertion bindings, the `C-h'
443 and `h' should be mnemonic.
445 In the rest of this manual, I will assume you are using the defaults
446 for the mode prefix (`C-c %') and the command and insertion modifiers.
447 You can customize them, however; *Note Key Bindings::.
450 File: mmm.info, Node: Submode Classes, Next: Selecting Classes, Prev: MMM Minor Mode, Up: Basics
452 Understanding Submode Classes
453 =============================
455 A submode class represents a "type" of submode region. It specifies
456 how to find the regions, what their delimiters look like, what submode
457 they should be, how to insert them, and how they behave in other ways.
458 It is represented by a symbol, such as `mason' or `eval-elisp'.
460 For example, in the Mason set of classes, there is one class
461 representing all `<%...%>' inline Perl regions, and one representing
462 regions such as `<%perl>...</%perl>', `<%init>...</%init>', and so on.
463 These are different to Mason, but to Emacs they are all just Perl
464 sections, so they are covered by the same submode class.
466 But it would be tedious if whenever we wanted to use the Mason
467 classes, we had to specify both of these. (Actually, this is a
468 simplification: there are some half a dozen Mason submode classes.) So
469 submode classes can also "group" others together, and we can refer to
470 the `mason' class and mean all of them.
472 The way a submode class is used is to "apply" it to a buffer. This
473 scans the buffer for regions which should be submode regions according
474 to that class, and also remembers the class for later, so that new
475 submode regions can be inserted and scanned for later.
478 File: mmm.info, Node: Selecting Classes, Next: Insertion, Prev: Submode Classes, Up: Basics
480 How MMM Mode selects submode classes
481 ====================================
483 Submode classes that apply to a buffer come from three sources:
484 mode/extension-associated classes, file-local classes, and interactive
485 MMM-ification (*note Interactive::). Whenever MMM Mode is turned on in a
486 buffer (*note MMM Minor Mode::, and *Note Global Mode::), it inspects
487 the value of two variables to determine which classes to automatically
488 apply to the buffer. This covers the first two sources; the latter is
489 covered in a later chapter.
493 * File Classes:: Classes for a single file.
494 * Mode-Ext Classes:: Classes for a given mode or extension.
495 * Global Classes:: Classes for all MMM Mode buffers.
498 File: mmm.info, Node: File Classes, Next: Mode-Ext Classes, Prev: Selecting Classes, Up: Selecting Classes
500 File-Local Submode Classes
501 --------------------------
503 - Variable: mmm-classes
504 This variable is always buffer-local when set. Its value should be
505 either a single symbol or a list of symbols. Each symbol
506 represents a submode class that is applied to the buffer.
508 `mmm-classes' is usually set in a file local variables list. *Note
509 File Variables: (emacs)File Variables. The easiest way to do this is
510 for the first line of the file to contain the string `-*- mmm-classes:
511 CLASSES -*-', where CLASSES is the desired value of `mmm-classes' for
512 the file in question. It can also be done with a local variables list
513 at the end of the file.
516 File: mmm.info, Node: Mode-Ext Classes, Next: Global Classes, Prev: File Classes, Up: Selecting Classes
518 Submode Classes Associated with Modes and Extensions
519 ----------------------------------------------------
521 - User Option: mmm-mode-ext-classes-alist
522 This global variable associates certain submode classes with major
523 modes and/or file extensions. Its value is a list of elements of
524 the form `(MODE EXT CLASS)'. Any buffer whose major mode is MODE
525 (a symbol) _and_ whose file name matches EXT (a regular
526 expression) will automatically have the submode class CLASS
529 If MODE is `nil', then only EXT is considered to determine if a
530 buffer fits the criteria, and vice versa. Thus if both MODE and
531 EXT are nil, then CLASS is applied to _all_ buffers in which MMM
532 Mode is on. Note that EXT can be any regular expression, although
533 its name indicates that it most often refers to the file extension.
535 If CLASS is the symbol `t', then no submode class is actually
536 applied for this association. However, if `mmm-global-mode' is
537 non-`nil' and non-`t', MMM Mode will be turned on in matching
538 buffers even if there are no actual submode classes being applied.
541 - Function: mmm-add-mode-ext-class MODE EXT CLASS
542 This function adds an element to `mmm-mode-ext-classes-alist',
543 associating the submode class CLASS with the major mode MODE and
546 Older versions of MMM Mode required this function to be used to
547 control the value of `mmm-mode-ext-classes-alist', rather than
548 setting it directly. In this version it is provided purely for
549 convenience and backward compatibility.
552 File: mmm.info, Node: Global Classes, Prev: Mode-Ext Classes, Up: Selecting Classes
554 Globally Applied Classes and the Universal Class
555 ------------------------------------------------
557 In addition to file-local and mode-ext-associated submode classes,
558 MMM Mode also allows you to specify that certain submode classes apply
559 to _all_ buffers in which MMM Mode is enabled.
561 - User Option: mmm-global-classes
562 This variable's value should be a list of submode classes that
563 apply to all buffers with MMM Mode on. It can be overriden in a
564 file local variables list, such as to disable global class for a
565 specific file. Its default value is `(universal)'.
567 The default global class is the "universal class", which is defined
568 in the file `mmm-univ.el' (loaded automatically), and allows the author
569 of text to specify that a certain section of it be in a specific major
570 mode. Thus, for example, when writing an email message that includes
571 sample code, the author can allow readers of the message (who use emacs
572 and MMM) to view the code in the appropriate major mode. The syntax
573 used is `{%MODE%} ... {%/MODE%}', where MODE should be the name of the
574 major mode, with or without the customary `-mode' suffix: for example,
575 both `cperl' and `cperl-mode' are acceptable.
577 The universal class also defines an insertion key, `/', which
578 prompts for the submode to use. *Note Insertion::. The universal class
579 is most useful when `mmm-global-mode' is set to `t'; *Note Global
583 File: mmm.info, Node: Insertion, Next: Re-parsing, Prev: Selecting Classes, Up: Basics
585 Inserting new submode regions
586 =============================
588 So much for noticing submode regions already present when you open a
589 file. When editing a file with MMM Mode on, you will often want to add a
590 new submode region. MMM Mode provides several facilities to help you.
591 The simplest is to just hit a few keys and have the region and its
592 delimiters inserted for you.
594 Each submode class can define an association of keystrokes with
595 "skeletons" to insert a submode region. If there are several submode
596 classes enabled in a buffer, it is conceivable that the keys they use
597 for insertion might conflict, but unlikely as most buffers will not use
598 more than one or two submode classes groups.
600 As an example of how insertion works, consider the Mason classes. In
601 a buffer with MMM Mode enabled and Mason associated, the key sequence
602 `C-c % p' inserts the following perl section (the semicolon is to
603 prevent CPerl Mode from getting confused--*note Mason::):
609 In this schematic representation, the string `-!-' represents the
610 position of point (the cursor), `-<-' represents the beginning of the
611 submode region, and `->-' its end.
613 All insertion keys come after the MMM Mode prefix keys (by default
614 `C-c %'; *note Key Bindings::) and are by default single characters
615 such as `p', `%', and `i'. To avoid confusion, all the MMM Mode
616 commands are bound by default to control characters (after the same
617 prefix keys), such as `C-b', `C-%' and `C-r'. This is a change from
618 earlier versions of MMM Mode, and can be customized; see *Note Key
621 To find out what insertion keys are available, consult the
622 documentation for the submode class you are using. If it is one of the
623 classes supplied with MMM Mode, you can find it in this Info file.
625 Because insertion keys are implemented with a "default binding" for
626 flexibility, they do not show up in the output of `C-h m' and cannot be
627 found with `C-h k'. For this reason, MMM Mode supplies the command `C-c
628 % h' (`mmm-insertion-help' to view the available insertion keys.
631 File: mmm.info, Node: Re-parsing, Next: Interactive, Prev: Insertion, Up: Basics
633 Re-Parsing Submode Regions
634 ==========================
636 Describe `mmm-parse-buffer', `mmm-parse-region', `mmm-parse-block',
637 and `mmm-clear-current-region'.
640 File: mmm.info, Node: Interactive, Next: Global Mode, Prev: Re-parsing, Up: Basics
642 Interactive MMM-ification Functions
643 ===================================
645 There are several commands you can use to create submode regions
646 interactively, rather than by applying a submode class to a buffer.
647 These commands (in particular, `mmm-ify-region'), can be useful when
648 editing a file or email message containing a snippet of code in some
649 other language. Also see *Note Global Classes::, for an alternate
650 approach to the same problem.
653 Creates a submode region between point and mark. Prompts for the
654 submode to use, which must be a valid Emacs major mode name, such
655 as `emacs-lisp-mode' or `cperl-mode'. Adds markers to the
656 interactive history. (`mmm-ify-region')
659 Applies an already-defined submode class to the buffer, which it
660 prompts for. Adds this class to the interactive history.
664 Scans the buffer for submode regions (prompts for the submode)
665 using front and back regular expressions that it also prompts for.
666 Briefly, it starts at the beginning of the buffer and searches for
667 the front regexp. If it finds a match, it searches for the back
668 regexp. If it finds a match for that as well, it makes a submode
669 region between the two matches and continues searching until no
670 more matches are found. Adds the regexps to the interactive
671 history. (`mmm-ify-by-regexp')
673 These commands are also useful when designing a new submode class
674 (*note Submode Classes::). Working with the regexps interactively can
675 make it easier to debug and tune the class before starting to use it on
676 automatic. All these commands also add to value of the following
679 - Variable: mmm-interactive-history
680 Stores a history of all interactive mmm-ification that has been
681 performed in the current buffer. This way, for example, the
682 re-parsing functions (*note Re-parsing::) will respect
683 interactively added regions, and the insertion keys for classes
684 that were added interactively are available.
686 If for any reason you want to "wipe the slate clean", this command
687 should help you. By default, it has no key binding, so you must invoke
688 it with `M-x mmm-clear-history <RET>'.
690 - Command: mmm-clear-history
691 Clears all history of interactive mmm-ification in the current
692 buffer. This command does not affect existing submode regions; to
693 remove them, you may want to re-parse the buffer with `C-c % C-b'
694 (`mmm-parse-buffer').
697 File: mmm.info, Node: Global Mode, Prev: Interactive, Up: Basics
702 When a file has associated submode classes (*note Selecting
703 Classes::), you may want MMM Mode to turn itself on and parse that file
704 for submode regions automatically whenever it is opened in an Emacs
705 buffer. The value of the following variable controls when MMM Mode
706 turns itself on automatically.
708 - User Option: mmm-global-mode
709 Do not be misled by the fact that this variable's name ends in
710 `-mode': it is not a simple on/off switch. There are three possible
711 (meanings of) values for it: `t', `nil', and anything else.
713 When this variable is `nil', MMM Mode is never enabled
714 automatically. If it is enabled manually, such as by typing `M-x
715 mmm-mode', any submode classes associated with the buffer will
716 still be used, however.
718 When this variable is `t', MMM Mode is enabled automatically in
719 _all_ buffers, including those not visiting files, except those
720 whose major mode is an element of `mmm-never-modes'. The default
721 value of this variable contains modes such as `help-mode' and
722 `dired-mode' in which most users would never want MMM Mode, and in
723 which MMM might cause problems.
725 When this variable is neither `nil' nor `t', MMM Mode is enabled
726 automatically in all buffers that would have associated submode
727 classes; i.e. only if there would be something for it to do. The
728 value of `mmm-never-modes' is still respected, however. Note that
729 this can include buffers not visiting files, if that buffer's
730 major mode is present in `mmm-mode-ext-classes-alist' with a `nil'
731 value for EXT (*note Mode-Ext Classes::). Submode class values of
732 `t' in `mmm-mode-ext-classes-alist' cause MMM Mode to be enabled in
733 matching buffers, but supply no submode classes to be applied.
737 * Major Mode Hook:: Using MMM's Major Mode Hook
740 File: mmm.info, Node: Major Mode Hook, Prev: Global Mode, Up: Global Mode
745 This section is intended for users who understand Emacs Lisp and
746 want to know how MMM Global Mode is implemented, and perhaps use the
747 same technique. In fact, MMM Mode exports a hook variable that you can
748 use easily, without understanding any of the details--see below.
750 In order to enable itself in _all_ buffers, however, MMM Mode has to
751 hook itself into all major modes. Global Font Lock Mode from the
752 standard Emacs distribution (*note Font Lock: (emacs)Font Lock.) has a
753 similar problem, and solves it by adding a function to
754 `change-major-mode-hook', which is run by `kill-all-local-variables',
755 which is run in turn by all major mode functions at the _beginning_.
756 This function stores a list of which buffers need fontification. It
757 then adds a different function to `post-command-hook', which checks if
758 the current buffer needs fontification, and if so performs it. MMM
759 Global Mode uses the same technique.
761 In the interests of generality, and for your use, the function that
762 MMM Mode runs in `post-command-hook' (`mmm-run-major-mode-hook') is not
763 specific to MMM Mode, but rather runs the hook variable
764 `mmm-major-mode-hook', which by default contains a function
765 (`mmm-mode-on-maybe') which possibly turns MMM Mode on, depending on
766 the value of `mmm-global-mode'. Thus, to run another function in all
767 major modes, all you need to do is add it to this hook. For example,
768 the following line in an initialization file will turn on Auto Fill
769 Mode (*note Auto Fill: (emacs)Auto Fill.) in all buffers:
771 (add-hook 'mmm-major-mode-hook 'turn-on-auto-fill)
774 File: mmm.info, Node: Customizing, Next: Supplied Classes, Prev: Basics, Up: Top
779 This chapter explains how to customize the appearance and
780 functioning of MMM Mode however you want.
784 * Region Coloring:: Changing or removing background colors.
785 * Preferred Modes:: Choosing which major modes to use.
786 * Mode Line:: What is displayed in the mode line.
787 * Key Bindings:: Customizing the MMM Mode key bindings.
788 * Local Variables:: What local variables are saved for submodes.
789 * Changing Classes:: Changing the supplied submode classes.
790 * Hooks:: How to make MMM Mode run your code.
793 File: mmm.info, Node: Region Coloring, Next: Preferred Modes, Prev: Customizing, Up: Customizing
795 Customizing Region Coloring
796 ===========================
798 By default, MMM Mode highlights all submode regions with a background
799 color. There are three levels of this decoration, controlled by the
802 - User Option: mmm-submode-decoration-level
803 This variable controls the level of coloring of submode regions.
804 It should be one of the integers 0, 1, or 2, representing
805 (respectively) none, low, and high coloring.
807 No coloring means exactly that. Submode regions have the same
808 background as the rest of the text. This produces the minimal
809 interference with font-lock coloration. In particular, if you want to
810 use background colors for font-lock, this may be a good idea, because
811 the submode highlight, if present, overrides any font-lock background
814 Low coloring uses the same background color for all submode regions.
815 This color is specified with the face `mmm-default-submode-face' (*note
816 Faces: (emacs)Faces.) which can be customized, either through the Emacs
817 "customize" interface or using direct Lisp commands such as
818 `set-face-background'. Of course, other aspects of the face can also
819 be set, such as the foreground color, bold, underline, etc. These are
820 more likely to conflict with font-lock, however, so only a background
821 color is recommended.
823 High coloring uses multiple background colors, depending on the
824 function of the submode region. The recognized functions and their
825 meanings are as follows:
828 Code that is executed at the beginning of (something), as
829 initialization of some sort.
832 Code that is executed at the end of (something), as some sort of
836 Code that provides declarations of some sort, perhaps global or
837 local arguments, variables, or methods.
840 Text that is not executed as code, but instead serves to document
841 the code around it. Submode regions of this function often use a
842 mode such as Text Mode rather than a programming language mode.
845 An expression that is evaluated and its value interpolated into the
849 Executed code not falling under any other category.
852 Submode regions not falling under any other category, such as
855 The different background colors are provided by the faces
856 `mmm-FUNCTION-submode-face', which can be customized in the same way as
857 `mmm-default-submode-face'.
860 File: mmm.info, Node: Preferred Modes, Next: Mode Line, Prev: Region Coloring, Up: Customizing
862 Preferred Major Modes
863 =====================
865 Certain of the supplied submode classes know only the language that
866 certain sections are written in, but not what major mode you prefer to
867 use to edit such code. For example, many people prefer CPerl mode over
868 Perl mode; you may have a special mode for Javascript or just use C++
869 mode. This variable allows you to tell submodes such as Mason (*note
870 Mason::) and Embedded Javascript (*note Javascript::) what major mode
871 to use for the submodes:
873 - User Option: mmm-major-mode-preferences
874 The elements of this list are cons cells of the form `(LANGUAGE .
875 MODE)'. LANGUAGE should be a symbol such as `perl', `html-js', or
876 `java', while MODE should be the name of a major mode such as
877 `perl-mode', `cperl-mode', `javascript-mode', or `c++-mode'.
879 You probably won't have to set this variable at all; MMM tries to
880 make intelligent guesses about what modes you prefer. For
881 example, if a function called `javascript-mode' exists, it is
882 chosen, otherwise `c++-mode' is used. Similarly for `jde-mode' and
885 If you do need to change the defaults, you may find the following
888 - Function: mmm-set-major-mode-preferences LANGUAGE MODE &optional
890 Set the preferred major mode for LANGUAGE to MODE. If there is
891 already a mode specified for LANGUAGE, and DEFAULT is nil or
892 unsupplied, then it is changed. If DEFAULT is non-nil, then any
893 existing mode is unchanged. This is used by packages to ensure
894 that some mode is present, but not override any user-specified
895 mode. If you are not writing a submode class, you should ignore
898 Thus, for example, to use `my-java-mode' for Java code, you would
899 use the following line:
901 (mmm-set-major-mode-preferences 'java 'my-java-mode)
904 File: mmm.info, Node: Mode Line, Next: Key Bindings, Prev: Preferred Modes, Up: Customizing
906 Customizing the Mode Line Display
907 =================================
909 By default, when in a submode region, MMM Mode changes the section of
910 the mode line (*note Mode Line: (emacs)Mode Line.) that normally
911 displays the major mode name--for example, `HTML'--to instead show both
912 the dominant major mode and the currently active submode--for example,
913 `HTML[CPerl]'. You can change this format, however.
915 - User Option: mmm-submode-mode-line-format
916 The value of this variable should be a string containing one or
917 both of the escape sequences `~M' and `~m'. The string displayed
918 in the major mode section of the mode line when in a submode is
919 obtained by replacing all occurrences of `~M' with the dominant
920 major mode name and `~m' with the currently active submode name.
921 For example, to display only the currently active submode, set
922 this variable to `~m'. The default value is `~M[~m]'.
924 The MMM minor mode also normally displays the string `MMM' in the
925 minor mode section of the mode line to indicate when it is active. You
926 can customize or disable this as well.
928 - User Option: mmm-mode-string
929 This string is displayed in the minor mode section of the mode
930 line when the MMM minor mode is active. If nonempty, it should
931 begin with a space to separate the MMM indicator from that of
932 other minor modes. To eliminate the indicator entirely, set this
933 variable to the empty string.
936 File: mmm.info, Node: Key Bindings, Next: Local Variables, Prev: Mode Line, Up: Customizing
938 Customizing the MMM Mode Key Bindings
939 =====================================
941 The default MMM Mode key bindings are explained in *Note MMM Mode
942 Keys::, and in *Note Insertion::. There are a couple of ways to
943 customize these bindings.
945 - User Option: mmm-mode-prefix-key
946 The value of this variable (default is `C-c %') should be a key
947 sequence to use as the prefix for the MMM Mode keymap. Minor modes
948 typically use `C-c' followed by a punctuation character, but you
949 can change it to any user-available key sequence. To have an
950 effect, this variable should be set before MMM Mode is loaded.
952 - User Option: mmm-use-old-command-keys
953 When this variable is `nil', MMM Mode commands use the control
954 modifier and insertion keys no modifier. Any other value switches
955 the two, so that `mmm-parse-buffer', for example, is bound to `C-c
956 % b', while perl-section insertion in the Mason class is bound to
957 `C-c % C-p'. This variable should be set before MMM Mode is loaded
960 When MMM is loaded, it uses the value of `mmm-use-old-command-keys'
961 to set the values of the variables `mmm-command-modifiers' and
962 `mmm-insert-modifiers', so if you prefer you can set these variables
963 instead. They should each be a list of key modifiers, such as
964 `(control)' or `()'. The Meta modifier is used in some of the command
965 and insertion keys, so it should not be used, and the Shift modifier is
966 not particularly portable between Emacsen--if it works for you, feel
967 free to use it. Other modifiers, such as Hyper and Super, are not
968 universally available, but are valid when present.
971 File: mmm.info, Node: Local Variables, Next: Changing Classes, Prev: Key Bindings, Up: Customizing
973 Changing Saved Local Variables
974 ==============================
976 A lot of the functionality of MMM Mode--that which makes the major
977 mode appear to change--is implemented by saving and restoring the
978 values of local variables, or pseudo-variables. You can customize what
979 variables are saved, and how, with the following variable.
981 - Variable: mmm-save-local-variables
982 At its simplest, this is a list each of whose elements is a
983 buffer-local variable whose value is saved and restored for each
984 major mode. Each elements can also, however, be a list whose
985 first element is the variable symbol and whose subsequent elements
986 specify how and where the variable is to be saved. The second
987 element of the list, if present, should be one of the symbols
988 `global', `buffer', or `region'. If not present, the default
989 value is `global'. The third element, if present, should be a
990 list of major mode symbols in which to save the variable. In the
991 list form, the variable symbol itself can be replaced with a cons
992 cell of two functions, one to get the value and one to set the
993 value. This is called a "pseudo-variable".
995 Globally saved variables are the same in all (MMM-controlled) buffers
996 and submode regions of each major mode listed in the third argument, or
997 all major modes if it is `t' or not present. Buffer-saved variables
998 are the same in all submode regions of a given major mode in each
999 buffer, and region-saved variables can be different for each submode
1002 Pseudo-variables are used, for example, to save and restore the
1003 syntax table (*note Syntax: (emacs)Syntax.) and mode keymaps (*note
1004 Keymaps: (emacs)Keymaps.).
1007 File: mmm.info, Node: Changing Classes, Next: Hooks, Prev: Local Variables, Up: Customizing
1009 Changing the Supplied Submode Classes
1010 =====================================
1012 If you need to use MMM with a syntax for which a submode class is not
1013 supplied, and you have some facility with Emacs Lisp, you can write your
1014 own; see *Note Writing Classes::. However, sometimes you will only want
1015 to make a slight change to one of the supplied submode classes. You can
1016 do this, after that class is loaded, with the following functions.
1018 - Function: mmm-set-class-parameter CLASS PARAM VALUE
1019 Set the value of the keyword parameter PARAM of the submode class
1020 CLASS to VALUE. *Note Writing Classes::, for an explanation of
1021 the meaning of each keyword parameter. This creates a new
1022 parameter if one is not already present in the class.
1024 - Function: mmm-get-class-parameter CLASS PARAM
1025 Get the value of the keyword parameter PARAM for the submode class
1026 CLASS. Returns `nil' if there is no such parameter.
1029 File: mmm.info, Node: Hooks, Prev: Changing Classes, Up: Customizing
1031 Hooks Provided by MMM Mode
1032 ==========================
1034 MMM Mode defines several hook variables (*note Hooks: (emacs)Hooks.)
1035 which are run at different times. The most often used is
1036 `mmm-major-mode-hook' which is described in *Note Major Mode Hook::,
1037 but there are a couple others.
1039 - Variable: mmm-mode-hook
1040 This normal hook is run whenever MMM Mode is enabled in a buffer.
1042 - Variable: mmm-MAJOR-MODE-hook
1043 This is actually a whole set of hook variables, a different one for
1044 every major mode. Whenever MMM Mode is enabled in a buffer, the
1045 corresponding hook variable for the dominant major mode is run.
1047 - Variable: mmm-SUBMODE-submode-hook
1048 Again, this is a set of one hook variable per major mode. These
1049 hooks are run whenever a submode region of the corresponding major
1050 mode is created in any buffer, with point at the start of the new
1053 - Variable: mmm-CLASS-class-hook
1054 This is a set of one hook variable per submode class. These hooks
1055 are run when a submode class is first applied to a given buffer.
1057 Submode classes also have a `:creation-hook' parameter which should
1058 be a function to run whenever a submode region is created with that
1059 class, with point at the beginning of the submode region. This can be
1060 set for supplied submode classes with `mmm-set-class-parameter'; *Note
1064 File: mmm.info, Node: Supplied Classes, Next: Writing Classes, Prev: Customizing, Up: Top
1066 Supplied Submode Classes
1067 ************************
1069 This chapter describes the submode classes that are supplied with MMM
1074 * Mason:: Mason server-side Perl in HTML.
1075 * File Variables:: Elisp code in File Variables.
1076 * Here-documents:: Code in shell and Perl here-documents.
1077 * Javascript:: Javascript embedded in HTML.
1078 * Embedded CSS:: CSS Styles embedded in HTML.
1079 * Embperl:: Another syntax for Perl in HTML.
1080 * ePerl:: A general Perl-embedding syntax.
1081 * JSP:: Java code embedded in HTML.
1082 * RPM:: Shell scripts in RPM Spec Files.
1083 * Noweb:: Noweb literate programs.