1. 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. See section `Major Modes' in The Emacs Manual, for details.

MMM Mode is a general extension to Emacs which is useful whenever one file contains text in two or more programming languages, or that should be in two or more different modes. For example:

• 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. See section 4.3 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. See section 4.1 Mason: Perl in HTML, See section 4.6 Embperl: More Perl in HTML, See section 4.7 ePerl: General Perl Embedding, See section 4.8 JSP: Java Embedded in HTML.

• HTML itself can also contain embedded languages such as Javascript and CSS styles, for which Emacs has different major modes. See section 4.4 Javascript in HTML, and See section 4.5 CSS embedded in HTML, 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). See section 4.10 Noweb literate programming, for example.

• Emacs allows files of any type to contain `local variables', which can include Emacs Lisp code to be evaluated. See section `File Variables' in The Emacs Manual. It may be easier to edit this code in Emacs Lisp mode than in whatever mode is used for the rest of the file. See section 4.2 Elisp in a Local Variables List.

• There are many more possible uses for MMM Mode. RPM spec files can contain shell scripts (see section 4.9 RPM Spec Files). Email or newsgroup messages may contain sample code. And so on. We encourage you to experiment.

1.1 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' (see section `Choosing Modes' in The Emacs Manual). 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 (see section `Mode Line' in The Emacs Manual) changes to show which submode region is active. This can be configured; see 3.3 Customizing the Mode Line Display.
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 (see section 3.5 Changing Saved 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 (see section `Font Lock' in The Emacs Manual) fontifies correctly for the submode.
7. The submode regions are highlighted by a background color; see 3.1 Customizing 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. See section `Overlays' in The GNU Emacs Lisp Reference Manual, for more information on overlays.

Because overlays are not saved with a file, every time a file is opened, they must be created. Creating submode regions is occasionally referred to as 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.

1.2 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. See section 2.7 MMM Global Mode, for more detailed information.

1.3 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. See section 2.6 Interactive MMM-ification Functions, 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. See section 2.2 Understanding 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. See section `File Variables' in The Emacs Manual, for more information and other methods. Now whenever MMM Mode is turned on in that file, it will be mmm-ified according to 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. See section 2.7 MMM 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. See section 5. Writing Submode Classes, for more information.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.