This is mmm.info, produced by makeinfo version 4.2 from mmm.texinfo. INFO-DIR-SECTION GNU Emacs Lisp START-INFO-DIR-ENTRY * MMM-Mode: (mmm). Multiple Major Modes for Emacs END-INFO-DIR-ENTRY This is edition 0.4.8 of the MMM Mode Manual, last updated 9 March 2003. It documents version 0.4.8 of MMM Mode. Copyright 2000 Michael Abraham Shulman. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "Copying" and "GNU General Public License" are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  File: mmm.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) MMM Mode ******** MMM Mode is a minor mode for Emacs which allows Multiple Major Modes to coexist in a single buffer. This is edition 0.4.8 of the MMM Mode Manual, last updated 9 March 2003, which documents version 0.4.8 of MMM Mode. * Menu: * Overview:: An overview and introduction to MMM Mode. * Basics:: The basics of how to use it. * Customizing:: Customizing how it works to your needs. * Supplied Classes:: The supplied submode classes. * Writing Classes:: Writing your own submode classes. * Indices:: Just that. --- The Detailed Node Listing --- Overview of MMM Mode * Basic Concepts:: A simple explanation of how it works. * Installation:: How to install MMM Mode. * Quick Start:: Getting started using MMM Mode quickly. MMM Mode Basics * MMM Minor Mode:: The Emacs minor mode that manages it all. * Submode Classes:: What they are and how to use them. * Selecting Classes:: How MMM Mode knows what classes to use. * Insertion:: Inserting new submode regions automatically. * Re-parsing:: Re-scanning for submode regions. * Interactive:: Adding submode regions manually. * Global Mode:: Turning MMM Mode on automatically. The MMM Minor Mode * Enabling MMM Mode:: Turning MMM Mode on and off. * MMM Mode Keys:: Default key bindings in MMM Mode. How MMM Mode selects submode classes * File Classes:: Classes for a single file. * Mode-Ext Classes:: Classes for a given mode or extension. * Global Classes:: Classes for all MMM Mode buffers. MMM Global Mode * Major Mode Hook:: Using MMM's Major Mode Hook Customizing MMM Mode * Region Coloring:: Changing or removing background colors. * Preferred Modes:: Choosing which major modes to use. * Mode Line:: What is displayed in the mode line. * Key Bindings:: Customizing the MMM Mode key bindings. * Local Variables:: What local variables are saved for submodes. * Changing Classes:: Changing the supplied submode classes. * Hooks:: How to make MMM Mode run your code. Supplied Submode Classes * Mason:: Mason server-side Perl in HTML. * File Variables:: Elisp code in File Variables. * Here-documents:: Code in shell and Perl here-documents. * Javascript:: Javascript embedded in HTML. * Embedded CSS:: CSS Styles embedded in HTML. * Embperl:: Another syntax for Perl in HTML. * ePerl:: A general Perl-embedding syntax. * JSP:: Java code embedded in HTML. * RPM:: Shell scripts in RPM Spec Files. * Noweb:: Noweb literate programs. Writing Submode Classes * Basic Classes:: Writing a simple submode class. * Paired Delimiters:: Matching paired delimiters. * Region Placement:: Placing the region more accurately. * Submode Groups:: Grouping several classes together. * Calculated Submodes:: Deciding the submode at run-time. * Calculated Faces:: Deciding the display face at run-time. * Insertion Commands:: Inserting regions automatically. * Region Names:: Naming regions for syntax grouping. * Other Hooks:: Running code at arbitrary points. * Delimiters:: Controlling delimiter overlays. * Misc Keywords:: Other miscellaneous options. Indices * Concept Index:: Index of MMM Mode Concepts. * Function Index:: Index of functions and variables. * Keystroke Index:: Index of key bindings in MMM Mode.  File: mmm.info, Node: Overview, Next: Basics, Prev: Top, Up: Top Overview of MMM Mode ******************** MMM Mode is a minor mode for Emacs which allows Multiple Major Modes to coexist in a single buffer. The name is an abbreviation of `Multiple Major Modes'(1). A major mode is a customization of Emacs for editing a certain type of text, such as code for a specific programming language. *Note Major Modes: (emacs)Major Modes, for details. MMM Mode is a general extension to Emacs which is useful whenever one file contains text in two or more programming languages, or that should be in two or more different modes. For example: * CGI scripts written in any language, from Perl to PL/SQL, may want to output verbatim HTML, and the writer of such scripts may want to use Emacs' html-mode or sgml-mode to edit this HTML code, while remaining in the appropriate programming language mode for the rest of the file. *Note Here-documents::, for example. * There are now many "content delivery systems" which turn the CGI script idea around and simply add extra commands to an HTML file, often in some programming language, which are interpreted on the server. *Note Mason::, *Note Embperl::, *Note ePerl::, *Note JSP::. * HTML itself can also contain embedded languages such as Javascript and CSS styles, for which Emacs has different major modes. *Note Javascript::, and *Note Embedded CSS::, for example. * The idea of "literate programming" requires the same file to contain documentation (written as text, html, latex, etc.) and code (in an appropriate programming language). *Note Noweb::, for example. * Emacs allows files of any type to contain `local variables', which can include Emacs Lisp code to be evaluated. *Note File Variables: (emacs)File Variables. It may be easier to edit this code in Emacs Lisp mode than in whatever mode is used for the rest of the file. *Note File Variables::. * There are many more possible uses for MMM Mode. RPM spec files can contain shell scripts (*note RPM::). Email or newsgroup messages may contain sample code. And so on. We encourage you to experiment. * Menu: * Basic Concepts:: A simple explanation of how it works. * Installation:: How to install MMM Mode. * Quick Start:: Getting started using MMM Mode quickly. ---------- Footnotes ---------- (1) The name is derived from `mmm.el' for XEmacs by Gongquan Chen , from which MMM Mode was adapted.  File: mmm.info, Node: Basic Concepts, Next: Installation, Prev: Overview, Up: Overview Basic Concepts ============== The way MMM Mode works is as follows. Each buffer has a "dominant" or "default" major mode, which is chosen as major modes normally are: the user can set it interactively, or it can be chosen automatically with `auto-mode-alist' (*note Choosing Modes: (emacs)Choosing Modes.). Within the file, MMM Mode creates "submode regions" within which other major modes are in effect. While the point is in a submode region, the following changes occur: 1. The local keymap is that of the submode. This means the key bindings for the submode are available, while those of the dominant mode are not. 2. The mode line (*note Mode Line: (emacs)Mode Line.) changes to show which submode region is active. This can be configured; see *Note Mode Line::. 3. The major mode menu, both on the menu bar and the mouse popup, are that of the submode. 4. Some local variables of the submode shadow those of the default mode (*note Local Variables::). For the user, this serves to help make Emacs behave as if the submode were the major mode. 5. The syntax table and indentation are those of the submode. 6. Font-lock (*note Font Lock: (emacs)Font Lock.) fontifies correctly for the submode. 7. The submode regions are highlighted by a background color; see *Note Region Coloring::. The submode regions are represented internally by Emacs Lisp objects known as "overlays". Some of the above are implemented by overlay properties, and others are updated by an MMM Mode function in `post-command-hook'. You don't need to know this to use MMM Mode, but it may make any error messages you come across more understandable. *Note Overlays: (elisp)Overlays, for more information on overlays. Because overlays are not saved with a file, every time a file is opened, they must be created. Creating submode regions is occasionally referred to as "mmm-ification". (I've never had occasion to pronounce this, but if I did I would probably say `mummification'. Like what they did in ancient Egypt.) You can mmm-ify a buffer interactively, but most often MMM Mode will find and create submode regions automatically based on a buffer's file extension, dominant mode, or local variables.  File: mmm.info, Node: Installation, Next: Quick Start, Prev: Basic Concepts, Up: Overview Installing MMM Mode =================== MMM Mode has a standard installation process. See the file INSTALL for generic information on this process. To summarize, unpack the archive, `cd' to the created MMM Mode directory, type `./configure', then `make', then `make install'. If all goes correctly, this will compile the MMM Mode elisp files, install them in your local site-lisp directory, and install the MMM Mode info file `mmm.info' in your local info directory. Now you need to configure your Emacs initialization file (usually `~/.emacs') to use MMM Mode. First, Emacs has to know where to find MMM Mode. In other words, the MMM Mode directory has to be in `load-path'. This can be done in the parent directory's `subdirs.el' file, or in the init file with a line such as: (add-to-list 'load-path "/path/to/site-lisp/mmm/") Once `load-path' is configured, MMM Mode must be loaded. You can load all of MMM Mode with the line (require 'mmm-mode) but if you use MMM Mode only rarely, it may not be desirable to load all of it at the beginning of every editing session. You can load just enough of MMM Mode so it will turn itself on when necessary and load the rest of itself, by using instead the line (require 'mmm-auto) in your initialization file. One more thing you may want to do right now is to set the variable `mmm-global-mode'. If this variable is `nil' (the default), MMM Mode will never turn itself on. If it is `t', MMM Mode will turn itself on in every buffer. Probably the most useful value for it, however, is the symbol `maybe' (actually, anything that is not `nil' and not `t'), which causes MMM Mode to turn itself on in precisely those buffers where it would be useful. You can do this with a line such as: (setq mmm-global-mode 'maybe) in your initialization file. *Note Global Mode::, for more detailed information.  File: mmm.info, Node: Quick Start, Prev: Installation, Up: Overview Getting Started Quickly ======================= Perhaps the simplest way to create submode regions is to do it interactively by specifying a region. First you must turn MMM Mode on--say, with `M-x mmm-mode'--then place point and mark around the area you want to make into a submode region, type `C-c % C-r', and enter the desired major mode. *Note Interactive::, for more details. A better way to add submode regions is by using submode classes, which store a lot of useful information for MMM Mode about how to add and manipulate the regions created. *Note Submode Classes::, for more details. There are several sample submode classes that come with MMM Mode, which are documented later in this manual. Look through these and determine if one of them fits your needs. If so, I suggest reading the comments on that mode. Then come back here to find out to use it. To apply a submode class to a buffer interactively, turn MMM Mode on as above, then type `C-c % C-c' and enter the name of the class. Submode regions should be added automatically, if there are any regions in the buffer appropriate to the submode class. If you want a given file to always use a given submode class, you can express this in a file variable: add a line containing the string `-*- mmm-classes: CLASS -*-' at the top of the file. *Note File Variables: (emacs)File Variables, for more information and other methods. Now whenever MMM Mode is turned on in that file, it will be mmm-ified according to CLASS. If `mmm-global-mode' is non-nil, then MMM Mode will turn itself on whenever a file with a `mmm-classes' local variable is opened. *Note Global Mode::, for more information. If you want a submode class to apply to _all_ files in a certain major mode or with a certain extension, add a line such as this to your initialization file: (mmm-add-mode-ext-class MODE EXTENSION CLASS) After this call, any file opened whose name matches the regular expression EXTENSION _and_ whose default mode is MODE will be automatically mmm-ified according to CLASS (assuming `mmm-global-mode' is non-nil). If one of EXTENSION or MODE is `nil', a file need only satisfy the other one to be mmm-ified. You can now read the rest of this manual to learn more about how MMM Mode works and how to configure it to your preferences. If none of the supplied submode classes fit your needs, then you can try to write your own. *Note Writing Classes::, for more information.  File: mmm.info, Node: Basics, Next: Customizing, Prev: Overview, Up: Top MMM Mode Basics *************** This chapter explains the most important parts of how to use MMM Mode. * Menu: * MMM Minor Mode:: The Emacs minor mode that manages it all. * Submode Classes:: What they are and how to use them. * Selecting Classes:: How MMM Mode knows what classes to use. * Insertion:: Inserting new submode regions automatically. * Re-parsing:: Re-scanning for submode regions. * Interactive:: Adding submode regions manually. * Global Mode:: Turning MMM Mode on automatically.  File: mmm.info, Node: MMM Minor Mode, Next: Submode Classes, Prev: Basics, Up: Basics The MMM Minor Mode ================== An Emacs minor mode is an optional feature which can be turned on or off in a given buffer, independently of the major mode. *Note Minor Modes: (emacs)Minor Modes. MMM Mode is implemented as a minor mode which manages the submode regions. This minor mode must be turned on in a buffer for submode regions to be effective. When activated, the MMM Minor mode is denoted by `MMM' in the mode line (*note Mode Line::). * Menu: * Enabling MMM Mode:: Turning MMM Mode on and off. * MMM Mode Keys:: Default key bindings in MMM Mode.  File: mmm.info, Node: Enabling MMM Mode, Next: MMM Mode Keys, Prev: MMM Minor Mode, Up: MMM Minor Mode Enabling MMM Mode ----------------- If `mmm-global-mode' is non-`nil' (*note Global Mode::), then the MMM minor mode will be turned on automatically whenever a file with associated submode classes is opened (*note Selecting Classes::). It is also turned on by interactive mmm-ification (*note Interactive::), although the interactive commands do not have key bindings when it is not on and must be invoked via `M-x'. You can also turn it on (or off) manually with `M-x mmm-mode', in which case it applies all submode classes associated with the buffer. Turning MMM Mode off automatically removes all submode regions from the buffer. - Command: mmm-mode ARG Toggle the state of MMM Mode in the current buffer. If ARG is supplied, turn MMM Mode on if and only if ARG is positive. - Function: mmm-mode-on Turn MMM Mode on unconditionally in the current buffer. - Function: mmm-mode-off Turn MMM Mode off unconditionally in the current buffer. - Variable: mmm-mode This variable represents whether MMM Mode is on in the current buffer. Do not set this variable directly; use one of the above functions.  File: mmm.info, Node: MMM Mode Keys, Prev: Enabling MMM Mode, Up: MMM Minor Mode Key Bindings in MMM Mode ------------------------ When MMM Mode is on, it defines a number of key bindings. By default, these are bound after the prefix sequence `C-c %'. Minor mode keymaps are supposed to use `C-c PUNCTUATION' sequences, and I find this one to be a good mnemonic because `%' is used by Mason to denote special tags. This prefix key can be customized; *Note Key Bindings::. There are two types of key bindings in MMM Mode: "commands" and "insertions". Command bindings run MMM Mode interactive functions to do things like re-parse the buffer or end the current submode region, and are defined statically as normal Emacs key-bindings. Insertion bindings insert submode region skeletons with delimiters into the buffer, and are defined dynamically, according to which submode classes (*note Submode Classes::) are in effect, via a keymap default binding. To distinguish between the two, MMM Mode uses distinct modifier keys for each. By default, command bindings use the control key (e.g. `C-c % C-b' re-parses the buffer), and insertion bindings do not (e.g. `C-c % p', when the Mason class is in effect, inserts a `<%perl>...' region). This makes the command bindings different from in previous versions, however, so the variable `mmm-use-old-bindings' is provided. If this variable is set to `t' before MMM Mode is loaded, the bindings will be reversed: insertion bindings will use the control key and command bindings will not. Normally, Emacs gives help on a prefix command if you type `C-h' after that command (e.g. `C-x C-h' displays all key bindings starting with `C-x'). Because of how insertion bindings are implemented dynamically with a default binding, they do not show up when you hit `C-c % C-h'. For this reason, MMM Mode defines the command `C-c % h' which displays a list of all currently valid insertion key sequences. If you use the defaults for command and insertion bindings, the `C-h' and `h' should be mnemonic. In the rest of this manual, I will assume you are using the defaults for the mode prefix (`C-c %') and the command and insertion modifiers. You can customize them, however; *Note Key Bindings::.  File: mmm.info, Node: Submode Classes, Next: Selecting Classes, Prev: MMM Minor Mode, Up: Basics Understanding Submode Classes ============================= A submode class represents a "type" of submode region. It specifies how to find the regions, what their delimiters look like, what submode they should be, how to insert them, and how they behave in other ways. It is represented by a symbol, such as `mason' or `eval-elisp'. For example, in the Mason set of classes, there is one class representing all `<%...%>' inline Perl regions, and one representing regions such as `<%perl>...', `<%init>...', and so on. These are different to Mason, but to Emacs they are all just Perl sections, so they are covered by the same submode class. But it would be tedious if whenever we wanted to use the Mason classes, we had to specify both of these. (Actually, this is a simplification: there are some half a dozen Mason submode classes.) So submode classes can also "group" others together, and we can refer to the `mason' class and mean all of them. The way a submode class is used is to "apply" it to a buffer. This scans the buffer for regions which should be submode regions according to that class, and also remembers the class for later, so that new submode regions can be inserted and scanned for later.  File: mmm.info, Node: Selecting Classes, Next: Insertion, Prev: Submode Classes, Up: Basics How MMM Mode selects submode classes ==================================== Submode classes that apply to a buffer come from three sources: mode/extension-associated classes, file-local classes, and interactive MMM-ification (*note Interactive::). Whenever MMM Mode is turned on in a buffer (*note MMM Minor Mode::, and *Note Global Mode::), it inspects the value of two variables to determine which classes to automatically apply to the buffer. This covers the first two sources; the latter is covered in a later chapter. * Menu: * File Classes:: Classes for a single file. * Mode-Ext Classes:: Classes for a given mode or extension. * Global Classes:: Classes for all MMM Mode buffers.  File: mmm.info, Node: File Classes, Next: Mode-Ext Classes, Prev: Selecting Classes, Up: Selecting Classes File-Local Submode Classes -------------------------- - Variable: mmm-classes This variable is always buffer-local when set. Its value should be either a single symbol or a list of symbols. Each symbol represents a submode class that is applied to the buffer. `mmm-classes' is usually set in a file local variables list. *Note File Variables: (emacs)File Variables. The easiest way to do this is for the first line of the file to contain the string `-*- mmm-classes: CLASSES -*-', where CLASSES is the desired value of `mmm-classes' for the file in question. It can also be done with a local variables list at the end of the file.  File: mmm.info, Node: Mode-Ext Classes, Next: Global Classes, Prev: File Classes, Up: Selecting Classes Submode Classes Associated with Modes and Extensions ---------------------------------------------------- - User Option: mmm-mode-ext-classes-alist This global variable associates certain submode classes with major modes and/or file extensions. Its value is a list of elements of the form `(MODE EXT CLASS)'. Any buffer whose major mode is MODE (a symbol) _and_ whose file name matches EXT (a regular expression) will automatically have the submode class CLASS applied to it. If MODE is `nil', then only EXT is considered to determine if a buffer fits the criteria, and vice versa. Thus if both MODE and EXT are nil, then CLASS is applied to _all_ buffers in which MMM Mode is on. Note that EXT can be any regular expression, although its name indicates that it most often refers to the file extension. If CLASS is the symbol `t', then no submode class is actually applied for this association. However, if `mmm-global-mode' is non-`nil' and non-`t', MMM Mode will be turned on in matching buffers even if there are no actual submode classes being applied. *Note Global Mode::. - Function: mmm-add-mode-ext-class MODE EXT CLASS This function adds an element to `mmm-mode-ext-classes-alist', associating the submode class CLASS with the major mode MODE and extension EXT. Older versions of MMM Mode required this function to be used to control the value of `mmm-mode-ext-classes-alist', rather than setting it directly. In this version it is provided purely for convenience and backward compatibility.  File: mmm.info, Node: Global Classes, Prev: Mode-Ext Classes, Up: Selecting Classes Globally Applied Classes and the Universal Class ------------------------------------------------ In addition to file-local and mode-ext-associated submode classes, MMM Mode also allows you to specify that certain submode classes apply to _all_ buffers in which MMM Mode is enabled. - User Option: mmm-global-classes This variable's value should be a list of submode classes that apply to all buffers with MMM Mode on. It can be overriden in a file local variables list, such as to disable global class for a specific file. Its default value is `(universal)'. The default global class is the "universal class", which is defined in the file `mmm-univ.el' (loaded automatically), and allows the author of text to specify that a certain section of it be in a specific major mode. Thus, for example, when writing an email message that includes sample code, the author can allow readers of the message (who use emacs and MMM) to view the code in the appropriate major mode. The syntax used is `{%MODE%} ... {%/MODE%}', where MODE should be the name of the major mode, with or without the customary `-mode' suffix: for example, both `cperl' and `cperl-mode' are acceptable. The universal class also defines an insertion key, `/', which prompts for the submode to use. *Note Insertion::. The universal class is most useful when `mmm-global-mode' is set to `t'; *Note Global Mode::.  File: mmm.info, Node: Insertion, Next: Re-parsing, Prev: Selecting Classes, Up: Basics Inserting new submode regions ============================= So much for noticing submode regions already present when you open a file. When editing a file with MMM Mode on, you will often want to add a new submode region. MMM Mode provides several facilities to help you. The simplest is to just hit a few keys and have the region and its delimiters inserted for you. Each submode class can define an association of keystrokes with "skeletons" to insert a submode region. If there are several submode classes enabled in a buffer, it is conceivable that the keys they use for insertion might conflict, but unlikely as most buffers will not use more than one or two submode classes groups. As an example of how insertion works, consider the Mason classes. In a buffer with MMM Mode enabled and Mason associated, the key sequence `C-c % p' inserts the following perl section (the semicolon is to prevent CPerl Mode from getting confused--*note Mason::): <%perl>-<-; -!- ->- In this schematic representation, the string `-!-' represents the position of point (the cursor), `-<-' represents the beginning of the submode region, and `->-' its end. All insertion keys come after the MMM Mode prefix keys (by default `C-c %'; *note Key Bindings::) and are by default single characters such as `p', `%', and `i'. To avoid confusion, all the MMM Mode commands are bound by default to control characters (after the same prefix keys), such as `C-b', `C-%' and `C-r'. This is a change from earlier versions of MMM Mode, and can be customized; see *Note Key Bindings::. To find out what insertion keys are available, consult the documentation for the submode class you are using. If it is one of the classes supplied with MMM Mode, you can find it in this Info file. Because insertion keys are implemented with a "default binding" for flexibility, they do not show up in the output of `C-h m' and cannot be found with `C-h k'. For this reason, MMM Mode supplies the command `C-c % h' (`mmm-insertion-help' to view the available insertion keys.  File: mmm.info, Node: Re-parsing, Next: Interactive, Prev: Insertion, Up: Basics Re-Parsing Submode Regions ========================== Describe `mmm-parse-buffer', `mmm-parse-region', `mmm-parse-block', and `mmm-clear-current-region'.  File: mmm.info, Node: Interactive, Next: Global Mode, Prev: Re-parsing, Up: Basics Interactive MMM-ification Functions =================================== There are several commands you can use to create submode regions interactively, rather than by applying a submode class to a buffer. These commands (in particular, `mmm-ify-region'), can be useful when editing a file or email message containing a snippet of code in some other language. Also see *Note Global Classes::, for an alternate approach to the same problem. `C-c % C-r' Creates a submode region between point and mark. Prompts for the submode to use, which must be a valid Emacs major mode name, such as `emacs-lisp-mode' or `cperl-mode'. Adds markers to the interactive history. (`mmm-ify-region') `C-c % C-c' Applies an already-defined submode class to the buffer, which it prompts for. Adds this class to the interactive history. (`mmm-ify-by-class') `C-c % C-x' Scans the buffer for submode regions (prompts for the submode) using front and back regular expressions that it also prompts for. Briefly, it starts at the beginning of the buffer and searches for the front regexp. If it finds a match, it searches for the back regexp. If it finds a match for that as well, it makes a submode region between the two matches and continues searching until no more matches are found. Adds the regexps to the interactive history. (`mmm-ify-by-regexp') These commands are also useful when designing a new submode class (*note Submode Classes::). Working with the regexps interactively can make it easier to debug and tune the class before starting to use it on automatic. All these commands also add to value of the following variable. - Variable: mmm-interactive-history Stores a history of all interactive mmm-ification that has been performed in the current buffer. This way, for example, the re-parsing functions (*note Re-parsing::) will respect interactively added regions, and the insertion keys for classes that were added interactively are available. If for any reason you want to "wipe the slate clean", this command should help you. By default, it has no key binding, so you must invoke it with `M-x mmm-clear-history '. - Command: mmm-clear-history Clears all history of interactive mmm-ification in the current buffer. This command does not affect existing submode regions; to remove them, you may want to re-parse the buffer with `C-c % C-b' (`mmm-parse-buffer').  File: mmm.info, Node: Global Mode, Prev: Interactive, Up: Basics MMM Global Mode =============== When a file has associated submode classes (*note Selecting Classes::), you may want MMM Mode to turn itself on and parse that file for submode regions automatically whenever it is opened in an Emacs buffer. The value of the following variable controls when MMM Mode turns itself on automatically. - User Option: mmm-global-mode Do not be misled by the fact that this variable's name ends in `-mode': it is not a simple on/off switch. There are three possible (meanings of) values for it: `t', `nil', and anything else. When this variable is `nil', MMM Mode is never enabled automatically. If it is enabled manually, such as by typing `M-x mmm-mode', any submode classes associated with the buffer will still be used, however. When this variable is `t', MMM Mode is enabled automatically in _all_ buffers, including those not visiting files, except those whose major mode is an element of `mmm-never-modes'. The default value of this variable contains modes such as `help-mode' and `dired-mode' in which most users would never want MMM Mode, and in which MMM might cause problems. When this variable is neither `nil' nor `t', MMM Mode is enabled automatically in all buffers that would have associated submode classes; i.e. only if there would be something for it to do. The value of `mmm-never-modes' is still respected, however. Note that this can include buffers not visiting files, if that buffer's major mode is present in `mmm-mode-ext-classes-alist' with a `nil' value for EXT (*note Mode-Ext Classes::). Submode class values of `t' in `mmm-mode-ext-classes-alist' cause MMM Mode to be enabled in matching buffers, but supply no submode classes to be applied. * Menu: * Major Mode Hook:: Using MMM's Major Mode Hook  File: mmm.info, Node: Major Mode Hook, Prev: Global Mode, Up: Global Mode The Major Mode Hook ------------------- This section is intended for users who understand Emacs Lisp and want to know how MMM Global Mode is implemented, and perhaps use the same technique. In fact, MMM Mode exports a hook variable that you can use easily, without understanding any of the details--see below. In order to enable itself in _all_ buffers, however, MMM Mode has to hook itself into all major modes. Global Font Lock Mode from the standard Emacs distribution (*note Font Lock: (emacs)Font Lock.) has a similar problem, and solves it by adding a function to `change-major-mode-hook', which is run by `kill-all-local-variables', which is run in turn by all major mode functions at the _beginning_. This function stores a list of which buffers need fontification. It then adds a different function to `post-command-hook', which checks if the current buffer needs fontification, and if so performs it. MMM Global Mode uses the same technique. In the interests of generality, and for your use, the function that MMM Mode runs in `post-command-hook' (`mmm-run-major-mode-hook') is not specific to MMM Mode, but rather runs the hook variable `mmm-major-mode-hook', which by default contains a function (`mmm-mode-on-maybe') which possibly turns MMM Mode on, depending on the value of `mmm-global-mode'. Thus, to run another function in all major modes, all you need to do is add it to this hook. For example, the following line in an initialization file will turn on Auto Fill Mode (*note Auto Fill: (emacs)Auto Fill.) in all buffers: (add-hook 'mmm-major-mode-hook 'turn-on-auto-fill)  File: mmm.info, Node: Customizing, Next: Supplied Classes, Prev: Basics, Up: Top Customizing MMM Mode ******************** This chapter explains how to customize the appearance and functioning of MMM Mode however you want. * Menu: * Region Coloring:: Changing or removing background colors. * Preferred Modes:: Choosing which major modes to use. * Mode Line:: What is displayed in the mode line. * Key Bindings:: Customizing the MMM Mode key bindings. * Local Variables:: What local variables are saved for submodes. * Changing Classes:: Changing the supplied submode classes. * Hooks:: How to make MMM Mode run your code.  File: mmm.info, Node: Region Coloring, Next: Preferred Modes, Prev: Customizing, Up: Customizing Customizing Region Coloring =========================== By default, MMM Mode highlights all submode regions with a background color. There are three levels of this decoration, controlled by the following variable: - User Option: mmm-submode-decoration-level This variable controls the level of coloring of submode regions. It should be one of the integers 0, 1, or 2, representing (respectively) none, low, and high coloring. No coloring means exactly that. Submode regions have the same background as the rest of the text. This produces the minimal interference with font-lock coloration. In particular, if you want to use background colors for font-lock, this may be a good idea, because the submode highlight, if present, overrides any font-lock background coloring. Low coloring uses the same background color for all submode regions. This color is specified with the face `mmm-default-submode-face' (*note Faces: (emacs)Faces.) which can be customized, either through the Emacs "customize" interface or using direct Lisp commands such as `set-face-background'. Of course, other aspects of the face can also be set, such as the foreground color, bold, underline, etc. These are more likely to conflict with font-lock, however, so only a background color is recommended. High coloring uses multiple background colors, depending on the function of the submode region. The recognized functions and their meanings are as follows: `init' Code that is executed at the beginning of (something), as initialization of some sort. `cleanup' Code that is executed at the end of (something), as some sort of clean up facility. `declaration' Code that provides declarations of some sort, perhaps global or local arguments, variables, or methods. `comment' Text that is not executed as code, but instead serves to document the code around it. Submode regions of this function often use a mode such as Text Mode rather than a programming language mode. `output' An expression that is evaluated and its value interpolated into the output produced. `code' Executed code not falling under any other category. `special' Submode regions not falling under any other category, such as component calls. The different background colors are provided by the faces `mmm-FUNCTION-submode-face', which can be customized in the same way as `mmm-default-submode-face'.  File: mmm.info, Node: Preferred Modes, Next: Mode Line, Prev: Region Coloring, Up: Customizing Preferred Major Modes ===================== Certain of the supplied submode classes know only the language that certain sections are written in, but not what major mode you prefer to use to edit such code. For example, many people prefer CPerl mode over Perl mode; you may have a special mode for Javascript or just use C++ mode. This variable allows you to tell submodes such as Mason (*note Mason::) and Embedded Javascript (*note Javascript::) what major mode to use for the submodes: - User Option: mmm-major-mode-preferences The elements of this list are cons cells of the form `(LANGUAGE . MODE)'. LANGUAGE should be a symbol such as `perl', `html-js', or `java', while MODE should be the name of a major mode such as `perl-mode', `cperl-mode', `javascript-mode', or `c++-mode'. You probably won't have to set this variable at all; MMM tries to make intelligent guesses about what modes you prefer. For example, if a function called `javascript-mode' exists, it is chosen, otherwise `c++-mode' is used. Similarly for `jde-mode' and `java-mode'. If you do need to change the defaults, you may find the following function convenient. - Function: mmm-set-major-mode-preferences LANGUAGE MODE &optional DEFAULT Set the preferred major mode for LANGUAGE to MODE. If there is already a mode specified for LANGUAGE, and DEFAULT is nil or unsupplied, then it is changed. If DEFAULT is non-nil, then any existing mode is unchanged. This is used by packages to ensure that some mode is present, but not override any user-specified mode. If you are not writing a submode class, you should ignore the third argument. Thus, for example, to use `my-java-mode' for Java code, you would use the following line: (mmm-set-major-mode-preferences 'java 'my-java-mode)  File: mmm.info, Node: Mode Line, Next: Key Bindings, Prev: Preferred Modes, Up: Customizing Customizing the Mode Line Display ================================= By default, when in a submode region, MMM Mode changes the section of the mode line (*note Mode Line: (emacs)Mode Line.) that normally displays the major mode name--for example, `HTML'--to instead show both the dominant major mode and the currently active submode--for example, `HTML[CPerl]'. You can change this format, however. - User Option: mmm-submode-mode-line-format The value of this variable should be a string containing one or both of the escape sequences `~M' and `~m'. The string displayed in the major mode section of the mode line when in a submode is obtained by replacing all occurrences of `~M' with the dominant major mode name and `~m' with the currently active submode name. For example, to display only the currently active submode, set this variable to `~m'. The default value is `~M[~m]'. The MMM minor mode also normally displays the string `MMM' in the minor mode section of the mode line to indicate when it is active. You can customize or disable this as well. - User Option: mmm-mode-string This string is displayed in the minor mode section of the mode line when the MMM minor mode is active. If nonempty, it should begin with a space to separate the MMM indicator from that of other minor modes. To eliminate the indicator entirely, set this variable to the empty string.  File: mmm.info, Node: Key Bindings, Next: Local Variables, Prev: Mode Line, Up: Customizing Customizing the MMM Mode Key Bindings ===================================== The default MMM Mode key bindings are explained in *Note MMM Mode Keys::, and in *Note Insertion::. There are a couple of ways to customize these bindings. - User Option: mmm-mode-prefix-key The value of this variable (default is `C-c %') should be a key sequence to use as the prefix for the MMM Mode keymap. Minor modes typically use `C-c' followed by a punctuation character, but you can change it to any user-available key sequence. To have an effect, this variable should be set before MMM Mode is loaded. - User Option: mmm-use-old-command-keys When this variable is `nil', MMM Mode commands use the control modifier and insertion keys no modifier. Any other value switches the two, so that `mmm-parse-buffer', for example, is bound to `C-c % b', while perl-section insertion in the Mason class is bound to `C-c % C-p'. This variable should be set before MMM Mode is loaded to have an effect. When MMM is loaded, it uses the value of `mmm-use-old-command-keys' to set the values of the variables `mmm-command-modifiers' and `mmm-insert-modifiers', so if you prefer you can set these variables instead. They should each be a list of key modifiers, such as `(control)' or `()'. The Meta modifier is used in some of the command and insertion keys, so it should not be used, and the Shift modifier is not particularly portable between Emacsen--if it works for you, feel free to use it. Other modifiers, such as Hyper and Super, are not universally available, but are valid when present.  File: mmm.info, Node: Local Variables, Next: Changing Classes, Prev: Key Bindings, Up: Customizing Changing Saved Local Variables ============================== A lot of the functionality of MMM Mode--that which makes the major mode appear to change--is implemented by saving and restoring the values of local variables, or pseudo-variables. You can customize what variables are saved, and how, with the following variable. - Variable: mmm-save-local-variables At its simplest, this is a list each of whose elements is a buffer-local variable whose value is saved and restored for each major mode. Each elements can also, however, be a list whose first element is the variable symbol and whose subsequent elements specify how and where the variable is to be saved. The second element of the list, if present, should be one of the symbols `global', `buffer', or `region'. If not present, the default value is `global'. The third element, if present, should be a list of major mode symbols in which to save the variable. In the list form, the variable symbol itself can be replaced with a cons cell of two functions, one to get the value and one to set the value. This is called a "pseudo-variable". Globally saved variables are the same in all (MMM-controlled) buffers and submode regions of each major mode listed in the third argument, or all major modes if it is `t' or not present. Buffer-saved variables are the same in all submode regions of a given major mode in each buffer, and region-saved variables can be different for each submode region. Pseudo-variables are used, for example, to save and restore the syntax table (*note Syntax: (emacs)Syntax.) and mode keymaps (*note Keymaps: (emacs)Keymaps.).  File: mmm.info, Node: Changing Classes, Next: Hooks, Prev: Local Variables, Up: Customizing Changing the Supplied Submode Classes ===================================== If you need to use MMM with a syntax for which a submode class is not supplied, and you have some facility with Emacs Lisp, you can write your own; see *Note Writing Classes::. However, sometimes you will only want to make a slight change to one of the supplied submode classes. You can do this, after that class is loaded, with the following functions. - Function: mmm-set-class-parameter CLASS PARAM VALUE Set the value of the keyword parameter PARAM of the submode class CLASS to VALUE. *Note Writing Classes::, for an explanation of the meaning of each keyword parameter. This creates a new parameter if one is not already present in the class. - Function: mmm-get-class-parameter CLASS PARAM Get the value of the keyword parameter PARAM for the submode class CLASS. Returns `nil' if there is no such parameter.  File: mmm.info, Node: Hooks, Prev: Changing Classes, Up: Customizing Hooks Provided by MMM Mode ========================== MMM Mode defines several hook variables (*note Hooks: (emacs)Hooks.) which are run at different times. The most often used is `mmm-major-mode-hook' which is described in *Note Major Mode Hook::, but there are a couple others. - Variable: mmm-mode-hook This normal hook is run whenever MMM Mode is enabled in a buffer. - Variable: mmm-MAJOR-MODE-hook This is actually a whole set of hook variables, a different one for every major mode. Whenever MMM Mode is enabled in a buffer, the corresponding hook variable for the dominant major mode is run. - Variable: mmm-SUBMODE-submode-hook Again, this is a set of one hook variable per major mode. These hooks are run whenever a submode region of the corresponding major mode is created in any buffer, with point at the start of the new submode region. - Variable: mmm-CLASS-class-hook This is a set of one hook variable per submode class. These hooks are run when a submode class is first applied to a given buffer. Submode classes also have a `:creation-hook' parameter which should be a function to run whenever a submode region is created with that class, with point at the beginning of the submode region. This can be set for supplied submode classes with `mmm-set-class-parameter'; *Note Changing Classes::.  File: mmm.info, Node: Supplied Classes, Next: Writing Classes, Prev: Customizing, Up: Top Supplied Submode Classes ************************ This chapter describes the submode classes that are supplied with MMM Mode. * Menu: * Mason:: Mason server-side Perl in HTML. * File Variables:: Elisp code in File Variables. * Here-documents:: Code in shell and Perl here-documents. * Javascript:: Javascript embedded in HTML. * Embedded CSS:: CSS Styles embedded in HTML. * Embperl:: Another syntax for Perl in HTML. * ePerl:: A general Perl-embedding syntax. * JSP:: Java code embedded in HTML. * RPM:: Shell scripts in RPM Spec Files. * Noweb:: Noweb literate programs.