-*-outline-*-
              Frequently Asked Questions about MMM Mode
              =========================================

* How do I write/capitalize the name of this package/mode?

However you want.  The author says `MMM Mode' (and occasionally `MMM')
when discussing the entire package, and `mmm-mode' when discussing the
emacs mode or function.  He does think, however, that `Mmm' looks
rather ugly, although that is how SourceForge insists on capitalizing
the name of the mailing list.


* How do I get rid of that ugly gray background color?

Put the following line in your Emacs initialization file:

  (setq mmm-submode-decoration-level 0)

You may want to try using MMM Mode for a while with the background
highlight, however, or merely changing it to a different color.  There
are two reasons it's there by default:

1. MMM Mode isn't as smart as you might hope it would be about
   recognizing new submode regions, so the presence or absence of the
   highlight can let you know at a glance where it thinks they are.

2. Just like the rest of font-lock, it helps you mentally organize the
   code; you can see at a glance that THIS code is executed as Perl,
   but THAT code is straight HTML (or whatever).  You can get even
   more help by setting the above variable to 2, in which case regions
   will get a background color according to their function.


* I typed `<%' (or other delimiter) but I'm still in the wrong mode.

MMM Mode isn't that smart yet.  You have to tell it explicitly to
reparse (`C-c % C-5' or `C-c % C-b') when you add new submode regions,
and both delimiters have to be present.  Hopefully a future version
will be able to automatically recognize new regions an you type them,
but that version is not yet here.

However, most submode classes provide insertion commands that remove
the need to type the delimiters as well as the need to reparse the
block: type `C-c % h' for a list of available insertion commands for
current submode class(es).

With a recent update, you can set `mmm-parse-when-idle' to t, to allow
MMM Mode to reparse the buffer when it's modified and Emacs is idle.
This comes at a certain performance cost.


* Why is the first character of the end delimiter in the submode region?

It isn't.  When your cursor looks like it is over that character, it
is actually *before* that character and therefore inside the submode
region.  You can check that the offending character does not have the
background highlight--that is, if you haven't set the decoration level
to 0.  For example, in the following text (where -!- represents the
cursor position)

  print <<END_TEXT;
  here is some text
  -!-END_TEXT

The 'E' at the beginning of the END_TEXT line is not actually part of
the submode region.  But with the cursor as indicated (that is, the
box is blinking over the `E' which follows the actual cursor
position), Emacs is in text-mode.


* Why won't MMM Mode work with `foo-mode'?

Foo-mode probably has extra variables or states that need to be set
up, that MMM Mode doesn't yet know about.  Often this sort of problem
can be fixed by adding elements to `mmm-save-local-variables'.  If you
know some Elisp, you may want to try and track down the problem
yourself, or you can contact the mailing list and ask for help.
Either way, please file an issue, so that in the future, folks can
use MMM Mode and foo-mode together more easily.


* I'm getting an emacs error, what did I do wrong?

Most likely nothing.  MMM Mode is still more or less alpha software
and is quite likely to contain bugs; probably something in your
configuration has brought a new bug to light.  Please send the text of
the error, along with a stack backtrace (1) and the relevant portions
of your emacs initialization file, to either the maintainer or the
mailing list, and hopefully a fix can be worked out.

Of course, it's also possible that there is an error in your
configuration.  Double-check the elisp syntax in your init file, or
inspect the backtrace yourself.  If the error happens while loading
your init code, try manually evaluating it line by line (`C-x C-e') to
see where the error occurs.  Folks on the mailing list can also help
point out errors, but only with your init code and a backtrace.

If you're having a problem with syntax highlighting, debugging is
complicated by the fact that font-lock swallows errors. To trigger the
error, evaluate the following in the problem buffer (with `M-:'):

  (font-lock-fontify-region (point-min) (point-max))

(1) To get a stack backtrace of an error, set the emacs variable
    `debug-on-error' to non-nil (type `M-x toggle-debug-on-error RET' or
    `M-: (setq debug-on-error t) RET'), then repeat the actions which
    caused the error. A stack backtrace should pop up which you can
    select and copy. If the error occurs while loading emacs, invoke
    emacs with the `--debug-init' (Emacs) or `-debug-init' (XEmacs)
    switch.


* Will MMM Mode work with (Emacs 23 / XEmacs 20 / XEmacs 21 / etc...)?

MMM Mode was designed for FSF Emacs and works best in versions 23 and 24.
But don't let that stop you from trying it under other variants of
emacs.  If you encounter problems, feel free to ask the mailing list,
but success is not guaranteed.

XEmacs 21 has problems with font-lock: for example, often apostrophes in
a different submode region can cause code to be incorrectly font-locked
as a string.

Versions of FSF Emacs < 23 and XEmacs < 21 are not supported.


* XEmacs says `Symbol's function definition is void: make-indirect-buffer'.

You probably used FSF Emacs to compile MMM as it is the one used by
default if both are installed.  To explicitly set the emacs to use
when byte compiling, do the following:

$ cd mmm-mode-x.x.x
$ make distclean
$ ./configure --with-xemacs=/path/to/xemacs
$ make
$ make install

Running `make distclean' is only necessary if you have already
compiled MMM Mode for the wrong emacs, but can never hurt.  The exact
error message this problem produces may change with newer versions of
MMM Mode; always be sure you have compiled for the correct emacsen.


* I want to install the Git version, but there's no `configure' script.

The `configure' script which is included in the official distributions
is not present in Git, because it is automatically generated by GNU
Automake/Autoconf from files like `Makefile.am' and `configure.in'.
To build the Git version the same way as the official distributions,
you must first run `autogen.sh':

$ cd mmm-mode
$ ./autogen.sh

and then you can continue as usual:

$ ./configure
$ make
$ make install

Note that autogen.sh requires aclocal, automake, and autoconf, which
may or may not be installed on your system, since they are considered
developer tools rather than end-user tools.  If you can't or don't
want to install them, however, you can still use the Git version of
MMM Mode by manually copying all the `.el' files into a directory in
your `load-path'.  Optionally, you may also byte-compile them manually
(this is what `make' normally does).  Byte-compiling gives some speed
improvement, but if you experience problems, the stack traces are
sometimes more informative if you are using the source files only.

The Info files `mmm.info-*' are also not included in Git, since they
are generated from `mmm.texinfo' by the program `makeinfo'.  If you
want to install the Info documentation from Git, you will have to run
this manually as well, and copy the resulting info files into the
appropriate location for your system.

The Git version is, of course, even less guaranteed to be bug-free
than the official distributions.  But please report any problems you
have with it, so they can be fixed for the next release.


* You haven't answered my question; how can I get more help?

Create an issue at <https://github.com/purcell/mmm-mode/issues>, or
check out the MMM Mode web site, <http://mmm-mode.sourceforge.net>,
there is a link to the subscription page for the MMM Mode mailing list.

When asking a question or reporting a problem, be sure to give the
versions of emacs and MMM Mode you are using, and any other relevant
information.