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: Mason, Next: File Variables, Prev: Supplied Classes, Up: Supplied Classes
35 Mason is a syntax to embed Perl code in HTML and other documents.
36 See `http://www.masonhq.com' for more information. The submode class
37 for Mason components is called `mason' and is loaded on demand from
38 `mmm-mason.el'. The current Mason class is intended to correctly
39 recognize all syntax valid in Mason 0.896. There are insertion keys
40 for most of the available syntax; use `mmm-insertion-help' (`C-c % h'
41 by default) with Mason on to get a list.
43 If you want to have mason submodes automatically in all Mason files,
44 you can use automatic mode and filename associations; the details
45 depend on what you call your Mason components and what major mode you
46 use. *Note Mode-Ext Classes::. If you use an extension for your Mason
47 files that emacs does not automatically place in your preferred HTML
48 Mode, you will probably want to associate that extension with your HTML
49 Mode as well; *Note Choosing Modes: (emacs)Choosing Modes. This also
50 goes for "special" Mason files such as autohandlers and dhandlers.
52 The Perl mode used is controlled by the user: *Note Preferred
53 Modes::. The default is to use CPerl mode, if present. Unfortunately,
54 there are also certain problems with CPerl mode in submode regions.
55 (Not to say that the original perl-mode would do any better--it hasn't
56 been much tried.) First of all, the first line of a Perl section is
57 usually indented as if it were a continuation line. A fix for this is
58 to start with a semicolon on the first line. The insertion key
59 commands do this whenever the Mason syntax allows it.
65 In addition, some users have reported that the CPerl indentation
66 sometimes does not work. This problem has not yet been tracked down,
67 however, and more data about when it happens would be helpful.
69 Some people have reported problems using PSGML with Mason. Adding
70 the following line to a `.emacs' file should suffice to turn PSGML off
71 and cause emacs to use a simpler HTML mode:
73 (autoload 'html-mode "sgml-mode" "HTML Mode" t)
75 Earlier versions of PSGML may require instead the following fix:
77 (delete '("\\.html$" . sgml-html-mode) auto-mode-alist)
78 (delete '("\\.shtml$" . sgml-html-mode) auto-mode-alist)
80 Other users report using PSGML with Mason and MMM Mode without
81 difficulty. If you don't have problems and want to use PSGML, you may
82 need to replace `html-mode' in the suggested code with
83 `sgml-html-mode'. (Depending on your version of PSGML, this may not be
84 necessary.) Similarly, if you are using XEmacs and want to use the
85 alternate HTML mode `hm--html-mode', replace `html-mode' with that
88 One problem that crops up when using PSGML with Mason is that even
89 ignoring the special tags and Perl code (which, as I've said, haven't
90 caused me any problems), Mason components often are not a complete SGML
91 document. For instance, my autohandlers often say
97 in which case the actual components contain no doctype declaration,
98 `<html>', `<head>', or `<body>', confusing PSGML. One solution I've
99 found is to use the variable `sgml-parent-document' in such incomplete
100 components; try, for example, these lines at the end of a component.
103 %# sgml-parent-document: ("autohandler" "body" nil ("body"))
104 %# sgml-doctype: "/top/level/autohandler"
107 This tells PSGML that the current file is a sub-document of the file
108 `autohandler' and is included inside a `<body>' tag, thus alleviating
112 File: mmm.info, Node: File Variables, Next: Here-documents, Prev: Mason, Up: Supplied Classes
114 Elisp in a Local Variables List
115 ===============================
117 Emacs allows the author of a file to specify major and minor modes
118 to be used while editing that file, as well as specifying values for
119 other local Elisp variables, with a File Variables list. *Note File
120 Variables: (emacs)File Variables. Since file variables values are
121 Elisp objects (and with the `eval' special "variable", they are forms
122 to be evaluated), one might want to edit them in `emacs-lisp-mode'.
123 The submode class `file-variables' allows this, and is suitable for
124 turning on in a given file with `mmm-classes', or in all files with
125 `mmm-global-classes'.
128 File: mmm.info, Node: Here-documents, Next: Javascript, Prev: File Variables, Up: Supplied Classes
133 One of the long-time standard syntaxes for outputting large amounts
134 of code (or text, or HTML, or whatever) from a script (notably shell
135 scripts and Perl scripts) is the here-document syntax:
140 <title>Test Page</title>
145 The `here-doc' submode class recognizes this syntax, and can even
146 guess the correct submode to use in many cases. For instance, it would
147 put the above example in `html-mode', noticing the string `HTML' in the
148 name of the here-document. If you use less than evocative
149 here-document names, or if the submode is recognized incorrectly for
150 any other reason, you can tell it explicitly what submode to use.
152 - User Option: mmm-here-doc-mode-alist
153 The value of this variable should be an alist, each element a cons
154 pair associating a regular expression to a submode symbol.
155 Whenever a here-document name matches one of these regexps, the
156 corresponding submode is applied. For example, if this variable
157 contains the element `("CODE" . cc-mode)', then any here-document
158 whose name contains the string `CODE' will be put in `cc-mode'.
159 The value of this variable overrides any guessing that the
160 `here-doc' submode class would do otherwise.
163 File: mmm.info, Node: Javascript, Next: Embedded CSS, Prev: Here-documents, Up: Supplied Classes
168 The submode class `html-js' allows for embedding Javascript code in
169 HTML documents. It recognizes both this syntax:
171 <script language="Javascript">
179 <input type="button" onClick="validate();">
181 The mode used for Javascript regions is controlled by the user;
182 *Note Preferred Modes::.
185 File: mmm.info, Node: Embedded CSS, Next: Embperl, Prev: Javascript, Up: Supplied Classes
190 CSS (Cascading Style Sheets) can also be embedded in HTML. The
191 `embedded-css' submode class recognizes this syntax:
199 It uses `css-mode' if present, `c++-mode' otherwise. This can be
200 customized: *Note Preferred Modes::.
203 File: mmm.info, Node: Embperl, Next: ePerl, Prev: Embedded CSS, Up: Supplied Classes
205 Embperl: More Perl in HTML
206 ==========================
208 Embperl is another syntax for embedding Perl in HTML. See
209 `http://perl.apache.org/embperl' for more information. The `embperl'
210 submode class recognizes most if not all of the Embperl embedding
211 syntax. Its Perl mode is also controllable by the user; *Note
215 File: mmm.info, Node: ePerl, Next: JSP, Prev: Embperl, Up: Supplied Classes
217 ePerl: General Perl Embedding
218 =============================
220 Yet another syntax for embedding Perl is called ePerl. See
221 `http://www.engelschall.com/sw/eperl/' for more information. The
222 `eperl' submode class handles this syntax, using the Perl mode
223 specified by the user; *Note Preferred Modes::.
226 File: mmm.info, Node: JSP, Next: RPM, Prev: ePerl, Up: Supplied Classes
228 JSP: Java Embedded in HTML
229 ==========================
231 JSP (Java Server Pages) is a syntax for embedding Java code in HTML.
232 The submode class `jsp' handles this syntax, using a Java mode
233 specified by the user; *Note Preferred Modes::. The default is
234 `jde-mode' if present, otherwise `java-mode'.
237 File: mmm.info, Node: RPM, Next: Noweb, Prev: JSP, Up: Supplied Classes
242 `mmm-rpm.el' contains the definition of an MMM Mode submode class
243 for editing shell script sections within RPM (Redhat Package Manager)
244 spec files. It is recommended for use in combination with
245 `rpm-spec-mode.el' by Stig Bjørlykke <stigb@tihlde.hist.no> and Steve
246 Sanbeg <sanbeg@dset.com>
247 (`http://www.xemacs.org/~stigb/rpm-spec-mode.el').
249 Suggested setup code:
251 (add-to-list 'mmm-mode-ext-classes-alist
252 '(rpm-spec-mode "\\.spec\\'" rpm-sh))
254 Thanks to Marcus Harnisch <Marcus.Harnisch@gmx.net> for contributing
258 File: mmm.info, Node: Noweb, Prev: RPM, Up: Supplied Classes
260 Noweb literate programming
261 ==========================
263 `mmm-noweb.el' contains the definition of an MMM Mode submode class
264 for editing Noweb documents. Most Noweb documents use \LaTeX for the
265 documentation chunks. Code chunks in Noweb are document-specific, and
266 the mode may be set with a local variable setting in the document. The
267 variable MMM-NOWEB-CODE-MODE controls the global code chunk mode. Since
268 Noweb files may have many languages in their code chunks, this mode
269 also allows setting the mode by specifying a mode in the first line or
270 two of a code chunk, using the normal Emacs first-line mode setting
271 syntax. Note that this first-line mode setting only matches a single
272 word for the mode name, and does not support the variable name setting
273 of the generalized first file line syntax.
276 % -*- mode: latex; mmm-noweb-code-mode: c++; -*-
277 % First chunk delimiter!
279 \noweboptions{smallcode}
281 \title{Sample Noweb File}
283 \nwanchorto{mailto:bozo@bozo.bozo}{\tt bozo@bozo.bozo}}
287 \section{Introduction}
288 Normal noweb documentation for the required [[*]] chunk.
291 // We might list the program here, or simply included chunks.
296 \section{[[myfile.cc]]}
297 This is [[myfile.cc]]. MMM noweb-mode understands code quotes in
300 // This section is indented separately from previous.
304 \section{A Perl Chunk}
305 We need a Perl chunk.
309 # Each differently named chunk is flowed separately.
312 \section{Finish [[myfile.cc]]}
313 When we resume a previously defined chunk, they are indented together.
315 // Pick up where we left off...
318 The quoted code chunks inside documentation chunks are given the mode
319 found in the variable MMM-NOWEB-QUOTE-MODE, if set, or the value in
320 MMM-NOWEB-CODE-MODE otherwise. Also, each quoted chunk is set to have
321 a unique name to prevent them from being indented as a unit.
323 Suggested setup code:
324 (mmm-add-mode-ext-class 'latex-mode "\\.nw\\'" 'noweb)
325 (add-to-list 'auto-mode-alist '("\\.nw\\'" . latex-mode))
327 In mmm-noweb buffers, each differently-named code chunk has a
328 different `:name', allowing all chunks with the same name to get
331 This mode also supplies special paragraph filling operations for use
332 in documentation areas of the buffer. From a primary-mode
333 (`latex-mode, , emacs') region, pressing `C-c % C-q' will mark all
334 submode regions with word syntax (`mmm-word-other-regions'), fill the
335 current paragraph (`(fill-paragraph justify)'), and remove the syntax
336 markings (`mmm-undo-syntax-other-regions').
338 Thanks to Joe Kelsey <joe@zircon.seattle.wa.us> for contributing this
342 File: mmm.info, Node: Writing Classes, Next: Indices, Prev: Supplied Classes, Up: Top
344 Writing Submode Classes
345 ***********************
347 Sometimes (perhaps often) you may want to use MMM with a syntax for
348 which it is suited, but for which no submode is supplied. In such cases
349 you may have to write your own submode class. This chapter briefly
350 describes how to write a submode class, from the basic to the advanced,
355 * Basic Classes:: Writing a simple submode class.
356 * Paired Delimiters:: Matching paired delimiters.
357 * Region Placement:: Placing the region more accurately.
358 * Submode Groups:: Grouping several classes together.
359 * Calculated Submodes:: Deciding the submode at run-time.
360 * Calculated Faces:: Deciding the display face at run-time.
361 * Insertion Commands:: Inserting regions automatically.
362 * Region Names:: Naming regions for syntax grouping.
363 * Other Hooks:: Running code at arbitrary points.
364 * Delimiters:: Controlling delimiter overlays.
365 * Misc Keywords:: Other miscellaneous options.
368 File: mmm.info, Node: Basic Classes, Next: Paired Delimiters, Prev: Writing Classes, Up: Writing Classes
370 Writing Basic Submode Classes
371 =============================
373 Writing a submode class can become rather complex, if the syntax to
374 match is complicated and you want to take advantage of some of MMM
375 Mode's extra features. But a simple submode class is not particularly
376 difficult to write. This section describes the basics of writing
379 Submode classes are stored in the variable `mmm-classes-alist'.
380 Each element of this list represents a single submode class. For
381 convenience, the function `mmm-add-classes' takes a list of submode
382 classes and adds them all to this alist. Each class is represented by a
383 list containing the class name--a symbol such as `mason' or
384 `html-js'--followed by pairs of keywords and arguments called a "class
385 specifier". For example, consider the specifier for the submode class
391 :face mmm-declaration-submode-face
392 :front "<style[^>]*>"
395 The name of the submode is `embedded-css', the first element of the
396 list. The rest of the list consists of pairs of keywords (symbols
397 beginning with a colon) such as `:submode' and `:front', and arguments,
398 such as `css' and `"<style[^>]*>"'. It is the keywords and arguments
399 that specify how the submode works. The order of keywords is not
400 important; all that matters is the arguments that follow them.
402 The three most important keywords are `:submode', `:front', and
403 `:back'. The argument following `:submode' names the major mode to use
404 in submode regions. It can be either a symbol naming a major mode,
405 such as `text-mode' or `c++-mode', or a symbol to look up in
406 `mmm-major-mode-preferences' (*note Preferred Modes::) such as `css',
409 The arguments following `:front' and `:back' are regular expressions
410 (*note Regexps: (emacs)Regexps.) that should match the delimiter
411 strings which begin and end the submode regions. In our example, CSS
412 regions begin with a `<style>' tag, possibly with parameters, and end
413 with a `</style>' tag.
415 The argument following `:face' specifies the face (background color)
416 to use when `mmm-submode-decoration-level' is 2 (high coloring). *Note
417 Region Coloring::, for a list of canonical available faces.
419 There are many more possible keywords arguments. In the following
420 sections, we will examine each of them and their uses in writing submode
424 File: mmm.info, Node: Paired Delimiters, Next: Region Placement, Prev: Basic Classes, Up: Writing Classes
426 Matching Paired Delimiters
427 ==========================
429 A simple pair of regular expressions does not always suffice to
430 exactly specify the beginning and end of submode regions correctly.
431 For this reason, there are several other possible keyword/argument
432 pairs which influence the matching process.
434 Many submode regions are marked by paired delimiters. For example,
435 the tags used by Mason (*note Mason::) include `<%init>...</%init>' and
436 `<%args>...</%args>'. It would be possible to write a separate submode
437 class for each type of region, but there is an easier way: the keyword
438 argument `:save-matches'. If supplied and non-nil, it causes the
439 regular expression `:back', before being searched for, to be formatted
440 by replacing all strings of the form `~N' (where N is an integer) with
441 the corresponding numbered subexpression of the match for `:front'. As
442 an example, here is an excerpt from the `here-doc' submode class.
443 *Note Here-documents::, for more information about this submode.
445 :front "<<\\([a-zA-Z0-9_-]+\\)"
449 The regular expression for `:front' matches `<<' followed by a
450 string of one or more alphanumeric characters, underscores, and dashes.
451 The latter string, which happens to be the name of the here-document, is
452 saved as the first subexpression, since it is surrounded by `\(...\)'.
453 Then, because the value of `:save-matches' is present and non-nil, the
454 string `~1' is replaced in the value of `:back' by the name of the
455 here-document, thus creating a regular expression to match the correct
459 File: mmm.info, Node: Region Placement, Next: Submode Groups, Prev: Paired Delimiters, Up: Writing Classes
461 Placing Submode Regions Precisely
462 =================================
464 Normally, a submode region begins immediately after the end of the
465 string matching the `:front' regular expression and ends immediately
466 before the beginning of the string matching the `:back' regular
467 expression. This can be changed with the keywords `:include-front' and
468 `:include-back'. If their arguments are `nil', or they do not appear,
469 the default behavior is unchanged. But if the argument of
470 `:include-front' (respectively, `:include-back') is non-nil, the
471 submode region will begin (respectively, end) immediately before
472 (respectively, after) the string matching the `:front' (respectively,
473 `:back') regular expression. In other words, these keywords specify
474 whether or not the delimiter strings are _included_ in the submode
477 When `:front' and `:back' are regexps, the delimiter is normally
478 considered to be the entire matched region. This can be changed using
479 the `:front-match' and `:back-match' keywords. The values of the
480 keywords is a number specifying the submatch. This defaults to zero
481 (specifying the whole regexp).
483 Two more keywords which affect the placement of the region
484 `:front-offset' and `:back-offset', which both take integers as
485 arguments. The argument of `:front-offset' (respectively,
486 `:back-offset') gives the distance in characters from the beginning
487 (respectively, ending) location specified so far, to the actual point
488 where the submode region begins (respectively, ends). For example, if
489 `:include-front' is nil or unsupplied and `:front-offset' is 2, the
490 submode region will begin two characters after the end of the match for
491 `:front', and if `:include-back' is non-nil and `:back-offset' is -1,
492 the region will end one character before the end of the match for
495 In addition to integers, the arguments of `:front-offset' and
496 `:back-offset' can be functions which are invoked to move the point
497 from the position specified by the matches and inclusions to the correct
498 beginning or end of the submode region, or lists whose elements are
499 either functions or numbers and whose effects are applied in sequence.
500 To help disentangle these options, here is another excerpt from the
501 `here-doc' submode class:
503 :front "<<\\([a-zA-Z0-9_-]+\\)"
504 :front-offset (end-of-line 1)
508 Here the value of `:front-offset' is the list `(end-of-line 1)',
509 meaning that from the end of the match for `:front', go to the end of
510 the line, and then one more character forward (thus to the beginning of
511 the next line), and begin the submode region there. This coincides
512 with the normal behavior of here-documents: they begin on the following
513 line and go until the ending flag.
515 If the `:back' should not be able to start a new submode region, set
516 the `:end-not-begin' keyword to non-nil.
519 File: mmm.info, Node: Submode Groups, Next: Calculated Submodes, Prev: Region Placement, Up: Writing Classes
521 Defining Groups of Submodes
522 ===========================
524 Sometimes more than one submode class is required to accurately
525 reflect the behavior of a single type of syntax. For example, Mason
526 has three very different types of Perl regions: blocks bounded by
527 matched tags such as `<%perl>...</%perl>', inline output expressions
528 bounded by `<%...%>', and single lines of code which simply begin with a
529 `%' character. In cases like these, it is possible to specify an
530 "umbrella" class, to turn all these classes on or off together.
532 - Function: mmm-add-group GROUP CLASSES
533 The submode classes CLASSES, which should be a list of lists,
534 similar to what might be passed to `mmm-add-classes', are added
535 just as by that function. Furthermore, another class named GROUP
536 is added, which encompasses all the classes in CLASSES.
538 Technically, an group class is specified with a `:classes' keyword
539 argument, and the subsidiary classes are given a non-nil `:private'
540 keyword argument to make them invisible. But in general, all you should
541 ever need to know is how to invoke the function above.
543 - Function: mmm-add-to-group GROUP CLASSES
544 Adds a list of classes to an already existing group. This can be
545 used, for instance, to add a new quoting definition to HTML-JS
546 using this example to add the quote characters "%=%":
548 (mmm-add-to-group 'html-js '((js-html
550 :face mmm-code-submode-face
556 File: mmm.info, Node: Calculated Submodes, Next: Calculated Faces, Prev: Submode Groups, Up: Writing Classes
558 Calculating the Correct Submode
559 ===============================
561 In most cases, the author of a submode class will know in advance
562 what major mode to use, such as `text-mode' or `c++-mode'. If there
563 are multiple possible modes that the user might desire, then
564 `mmm-major-mode-preferences' should be used (*note Preferred Modes::).
565 The function `mmm-set-major-mode-preferences' can be used, with a third
566 argument, to ensure than the mode is present.
568 In some cases, however, the author has no way of knowing in advance
569 even what language the submode region will be in. The `here-doc' class
570 is one of these. In such cases, instead of the `:submode' keyword, the
571 `:match-submode' keyword must be used. Its argument should be a
572 function, probably written by the author of the submode class, which
573 calculates what major mode each region should use.
575 It is invoked immediately after a match is found for `:front', and
576 is passed one argument: a string representing the front delimiter.
577 Normally this string is simply whatever was matched by `:front', but
578 this can be changed with the keyword `:front-form' (*note
579 Delimiters::). The function should then return a symbol that would be
580 a valid argument to `:submode': either the name of a mode, or that of a
581 language to look up a preferred mode. If it detects an invalid
582 match--for example, the user has specified a mode which is not
583 available--it should `(signal 'mmm-no-matching-submode nil)'.
585 Since here-documents can contain code in any language, the
586 `here-doc' submode class uses `:match-submode' rather than `:submode'.
587 The function it uses is `mmm-here-doc-get-mode', defined in
588 `mmm-sample.el', which inspects the name of the here-document for flags
589 indicating the proper mode. For example, this code should probably be
590 in `perl-mode' (or `cperl-mode'):
596 This function is also a good example of proper elisp hygiene: when
597 writing accessory functions for a submode class, they should usually be
598 prefixed with `mmm-' followed by the name of the submode class, to
599 avoid namespace conflicts.
602 File: mmm.info, Node: Calculated Faces, Next: Insertion Commands, Prev: Calculated Submodes, Up: Writing Classes
604 Calculating the Correct Highlight Face
605 ======================================
607 As explained in *Note Basic Classes::, the keyword `:face' should be
608 used to specify which of the standard submode faces (*note Region
609 Coloring::) a submode region should be highlighted with under high
610 decoration. However, sometimes the function of a region can depend on
611 the form of the delimiters as well. In this case, a more flexible
612 alternative to `:face' is `:match-face'. Its value can be a function,
613 which is called with one argument--the form of the front delimiter, as
614 with `:match-submode'--and should return the face to use. A more
615 common value for `:match-face' is an association list, a list of pairs
616 `(DELIM . FACE)', each specifying that if the delimiter is DELIM, the
617 corresponding region should be highlighted with FACE. For example,
618 here is an excerpt from the `embperl' submode class:
621 :front "\\[\\([-\\+!\\*\\$]\\)"
624 :match-face (("[+" . mmm-output-submode-face)
625 ("[-" . mmm-code-submode-face)
626 ("[!" . mmm-init-submode-face)
627 ("[*" . mmm-code-submode-face)
628 ("[$" . mmm-special-submode-face))
630 Thus, regions beginning with `[+' are highlighted as output
631 expressions, which they are, while `[-' and `[*' regions are
632 highlighted as simple executed code, and so on. Note that
633 MMM-SUBMODE-DECORATION-LEVEL must be set to 2 (high decoration) for
634 different faces to be displayed.
637 File: mmm.info, Node: Insertion Commands, Next: Region Names, Prev: Calculated Faces, Up: Writing Classes
639 Specifying Insertion Commands
640 =============================
642 As described in *Note Insertion::, submode classes can specify key
643 sequences which automatically insert submode regions, with delimiters
644 already in place. This is done by the keyword argument `:insert'. Its
645 value should be a list, each element of which specifies a single
646 insertion key sequence. As an example, consider the following insertion
647 key sequence specifier, from the `embperl' submode class:
649 (?p embperl "Region Type (Character): "
650 @ "[" str @ " " _ " " @ str "]" @)
652 As you can see, the specifier is a list. The first element of the
653 list is the character `p'. (The question mark tells Emacs that this is
654 a character object, not a one-character symbol.) In general, the first
655 element can be any key, including both characters such as `?p' and
656 function keys such as `return'. It can also be a dotted pair in which
657 the first element is a modifier symbol such as `meta', and the second
658 is a character or function key. The use of any other modifier than
659 meta is discouraged, as `mmm-insert-modifiers' is sometimes set to
660 \(control), and other modifiers are not very portable. The second
661 element is a symbol identifying this key sequence. The third element
662 is a prompt string which is used to ask the user for input when this
663 key sequence is invoked. If it is nil, the user is not prompted.
665 The rest of the list specifies the actual text to be inserted, where
666 the submode region and delimiters should be, and where the point should
667 end up. (Actually, this string is simply passed to `skeleton-insert';
668 see the documentation string of that function for more details on the
669 permissible elements of such a skeleton.) Strings and variable names
670 are inserted and interpolated. The value entered by the user when
671 prompted, if any, is available in the variable `str'. The final
672 location of the point (or the text around which the region is to be
673 wrapped) is marked with a single underscore `_'. Finally, the @-signs
674 mark the delimiters and submode regions. There should be four @-signs:
675 one at the beginning of the front delimiter, one at the beginning of
676 the submode region, one at the end of the submode region, and one at
677 the end of the back delimiter.
679 The above key sequence, bound by default to `C-c % p', always
680 prompts the user for the type of region to insert. It can also be
681 convenient to have separate key sequences for each type of region to be
682 inserted, such as `C-c % +' for `[+...+]' regions, `C-c % -' for
683 `[-...-]' regions, and so on. So that the whole skeleton doesn't have
684 to be written out half a dozen times, there is a shortcut syntax, as
687 (?+ embperl+ ?p . "+")
689 If the key sequence specification is a dotted list with four
690 elements, as this example is, it means to use the skeleton defined for
691 the key sequence given as the third element (`?p'), but to pass it the
692 fourth (dotted) element (`"+"') as the `str' variable; the user is not
696 File: mmm.info, Node: Region Names, Next: Other Hooks, Prev: Insertion Commands, Up: Writing Classes
698 Giving Names to Submode Regions for Grouping
699 ============================================
701 Submode regions can be given "names" which are used for grouping.
702 Names are always strings and are compared as strings. Regions with the
703 same name are considered part of the same chunk of code. This is used
704 by the syntax and fontification functions. Unnamed regions are not
705 grouped with any others.
707 By default, regions are nameless, but with the `:match-name' keyword
708 argument a name can be supplied. This argument must be a string or a
709 function. If it is a function, it is passed a string representing the
710 front delimiter found, and must return the name to use. If it is a
711 string, it is used as-is for the name, unless `:save-name' has a
712 non-nil value, in which case expressions such as `~1' are substituted
713 with the corresponding matched subexpression from `:front'. This is
714 the same as how `:back' is interpreted when `:save-matches' is non-nil.
716 As a special optimization for region insertion (*note Insertion
717 Commands::), the argument `:skel-name' can be set to a non-nil value,
718 in which case the insertion code will use the user-prompted string
719 value as the region name, instead of going through the normal matching
723 File: mmm.info, Node: Other Hooks, Next: Delimiters, Prev: Region Names, Up: Writing Classes
725 Other Hooks into the Scanning Process
726 =====================================
728 Sometimes, even the flexibility allowed by all the keyword arguments
729 discussed so far is insufficient to correctly match submode regions.
730 There are several other keyword arguments which accept custom functions
731 to be invoked at various points in the MMM-ification process.
733 First of all, the arguments of `:front' and `:back', in addition to
734 regular expressions, can be themselves functions. Such functions
735 should "act like" a regular expression search: they should start
736 searching at point, take one argument as a limit for the search, and
737 return its result by setting the match data (presumably by calling some
738 regexp matching function).
740 This is rarely necessary, however, because often all that is needed
741 is a simple regexp search, followed by some sort of verification. The
742 keyword arguments `:front-verify' and `:back-verify', if supplied, may
743 be functions which are invoked after a match is found for `:front' or
744 `:back', respectively, and should inspect the match data (such as with
745 `match-string') and return non-nil if a submode region should be begun
746 at this match, nil if this match should be ignored and the search
749 The keyword argument `:creation-hook', if supplied, should be a
750 function that is invoked whenever a submode region of this class is
751 created, with point at the beginning of the new region. This can be
752 used, for example, to set local variables appropriately.
754 Finally, the entire MMM-ification process has a "back door" which
755 allows class authors to take control of the entire thing. If the
756 keyword argument `:handler' is supplied, it overrides any other
757 processing and is called, and passed all other class keyword arguments,
758 instead of `mmm-ify' to create submode regions. If you need to write a
759 handler function, I suggest looking at the source for `mmm-ify' to get
760 an idea of what must be done.
763 File: mmm.info, Node: Delimiters, Next: Misc Keywords, Prev: Other Hooks, Up: Writing Classes
765 Controlling the Delimiter Regions and Forms
766 ===========================================
768 MMM also makes overlays for the delimiter regions, to keep track of
769 their position and form. Normally, the front delimiter overlay starts
770 at the beginning of the match for `:front' and ends at the beginning of
771 the submode region overlay, while the back delimiter overlay starts at
772 the end of the submode region overlay and ends at the end of the match
773 for `:back'. You can supply offsets from these positions using the
774 keyword arguments `:front-delim' and `:back-delim', which take values
775 of the same sort as `:front-offset' and `:back-offset'.
777 In addition, the delimiter regions can be in a major mode of their
778 own. There are usually only two meaningful modes to use: the primary
779 mode or a non-mode like fundamental-mode. These correspond to the
780 following two situations:
782 * If the delimiter syntax which specifies the submode regions is
783 something _added to_ the syntax of the primary mode by a
784 pre-interpreter, then the delimiter regions should be in a
785 non-mode. This is the case, for example, with all server-side
786 HTML script extensions, such as *Note Mason::, *Note Embperl::,
787 and *Note ePerl::. It is also the case for literate programming
788 such as *Note Noweb::. This is the default behavior. The
789 non-mode used is controlled by the variable `mmm-delimiter-mode',
790 which defaults to fundamental-mode.
792 * If, on the other hand, the delimiter syntax and inclusion of
793 different modes is an _intrinsic part_ of the primary mode, then
794 the delimiter regions should remain in the primary mode. This is
795 the case, for example, with *Note Embedded CSS::, and *Note
796 Javascript::, since the `<style>' and `<script>' tags are
797 perfectly valid HTML. In this case, you should give the keyword
798 parameter `:delimiter-mode' with a value of `nil', meaning to use
801 The keyword parameter `:delimiter-mode' can be given any major mode
802 as an argument, but the above two situations should cover the vast
805 The delimiter regions can also be highlighted, if you wish. The
806 keyword parameters `:front-face' and `:back-face' may be faces
807 specifying how to highlight these regions under high decoration. Under
808 low decoration, the value of the variable `mmm-delimiter-face' is used
809 (by default, nothing), and of course under no decoration there is no
812 Finally, for each submode region overlay, MMM Mode stores the "form"
813 of the front and back delimiters, which are regular expressions that
814 match the delimiters. At present these are not used for much, but in
815 the future they may be used to help with automatic updating of regions
816 as you type. Normally, the form stored is the result of evaluating the
817 expression `(regexp-quote (match-string 0))' after each match is found.
819 You can customize this with the keyword argument `:front-form'
820 (respectively, `:back-form'). If it is a string, it is used verbatim
821 for the front (respectively, back) form. If it is a function, that
822 function is called and should inspect the match data and return the
823 regular expression to use as the form.
825 In addition, the form itself can be set to a function, by giving a
826 one-element list containing only that function as the argument to
827 `:front-form' or `:back-form'. Such a function should take 1-2
828 arguments. The first argument is the overlay to match the delimiter
829 for. If the second is non-nil, it means to insert the delimiter and
830 adjust the overlay; if nil it means to match the delimiter and return
831 the result in the match data.
834 File: mmm.info, Node: Misc Keywords, Prev: Delimiters, Up: Writing Classes
836 Miscellaneous Other Keyword Arguments
837 =====================================
839 You can specify whether delimiter searches should be case-sensitive
840 with the keyword argument `:case-fold-search'. It defaults to `t',
841 meaning that case should be ignored. See the documentation for the
842 variable `case-fold-search'.
845 File: mmm.info, Node: Indices, Prev: Writing Classes, Up: Top
852 * Concept Index:: Index of MMM Mode Concepts.
853 * Function Index:: Index of functions and variables.
854 * Keystroke Index:: Index of key bindings in MMM Mode.
857 File: mmm.info, Node: Concept Index, Next: Function Index, Prev: Indices, Up: Indices
864 * class, mmm-ification by: Interactive.
865 * classes, submode: Submode Classes.
866 * clearing submode regions: Re-parsing.
867 * customizing submode faces: Region Coloring.
868 * default major mode: Basic Concepts.
869 * default submode face: Region Coloring.
870 * disabling mmm mode: Enabling MMM Mode.
871 * dominant major mode: Basic Concepts.
872 * enabling mmm mode: Enabling MMM Mode.
873 * faces, submode: Region Coloring.
874 * global mmm mode: Global Mode.
875 * history of interactive mmm-ification: Interactive.
876 * hook, major mode: Major Mode Hook.
877 * interactive mmm-ification: Interactive.
878 * interactive mmm-ification, history of: Interactive.
879 * key bindings in mmm mode: MMM Mode Keys.
880 * major mode hook: Major Mode Hook.
881 * major mode, default: Basic Concepts.
882 * major mode, dominant: Basic Concepts.
883 * minor mode, mmm: MMM Minor Mode.
884 * mmm global mode: Global Mode.
885 * mmm minor mode: MMM Minor Mode.
886 * mmm mode key bindings: MMM Mode Keys.
887 * mmm mode, disabling: Enabling MMM Mode.
888 * mmm mode, enabling: Enabling MMM Mode.
889 * mmm mode, turning off: Enabling MMM Mode.
890 * mmm mode, turning on: Enabling MMM Mode.
891 * mmm-ification: Basic Concepts.
892 * mmm-ification by class: Interactive.
893 * mmm-ification by regexp: Interactive.
894 * mmm-ification by region: Interactive.
895 * mmm-ification, interactive: Interactive.
896 * mmm-ification, interactive history: Interactive.
897 * mmm-mode, overview of: Overview.
898 * mode, mmm global: Global Mode.
899 * mode, mmm minor: MMM Minor Mode.
900 * overlays, submode: Basic Concepts.
901 * overview of mmm-mode: Overview.
902 * parsing submode regions: Re-parsing.
903 * re-parsing submode regions: Re-parsing.
904 * regexp, mmm-ification by: Interactive.
905 * region, mmm-ification by: Interactive.
906 * regions, submode: Basic Concepts.
907 * regions, submode, clearing: Re-parsing.
908 * regions, submode, re-parsing: Re-parsing.
909 * simple submode classes: Basic Classes.
910 * submode classes: Submode Classes.
911 * submode classes, simple: Basic Classes.
912 * submode faces: Region Coloring.
913 * submode overlays: Basic Concepts.
914 * submode regions: Basic Concepts.
915 * submode regions, clearing: Re-parsing.
916 * submode regions, re-parsing: Re-parsing.
917 * turning off mmm mode: Enabling MMM Mode.
918 * turning on mmm mode: Enabling MMM Mode.
921 File: mmm.info, Node: Function Index, Next: Keystroke Index, Prev: Concept Index, Up: Indices
923 Function and Variable Index
924 ===========================
929 * mmm-add-group: Submode Groups.
930 * mmm-add-mode-ext-class: Mode-Ext Classes.
931 * mmm-add-to-group: Submode Groups.
932 * mmm-classes: File Classes.
933 * mmm-clear-history: Interactive.
934 * mmm-get-class-parameter: Changing Classes.
935 * mmm-global-classes: Global Classes.
936 * mmm-global-mode: Global Mode.
937 * mmm-here-doc-mode-alist: Here-documents.
938 * mmm-insertion-help: MMM Mode Keys.
939 * mmm-interactive-history: Interactive.
940 * mmm-major-mode-hook: Major Mode Hook.
941 * mmm-major-mode-preferences: Preferred Modes.
942 * mmm-mode: Enabling MMM Mode.
943 * mmm-mode-ext-classes-alist: Mode-Ext Classes.
944 * mmm-mode-hook: Hooks.
945 * mmm-mode-off: Enabling MMM Mode.
946 * mmm-mode-on: Enabling MMM Mode.
947 * mmm-mode-prefix-key: Key Bindings.
948 * mmm-mode-string: Mode Line.
949 * mmm-never-modes: Global Mode.
950 * mmm-save-local-variables: Local Variables.
951 * mmm-set-class-parameter: Changing Classes.
952 * mmm-set-major-mode-preferences: Preferred Modes.
953 * mmm-submode-decoration-level: Region Coloring.
954 * mmm-submode-mode-line-format: Mode Line.
955 * mmm-use-old-command-keys: Key Bindings.
958 File: mmm.info, Node: Keystroke Index, Prev: Function Index, Up: Indices
965 * C-c % C-%: Re-parsing.
966 * C-c % C-5: Re-parsing.
967 * C-c % C-b: Re-parsing.
968 * C-c % C-c: Interactive.
969 * C-c % C-g: Re-parsing.
970 * C-c % C-k: Re-parsing.
971 * C-c % C-r: Interactive.
972 * C-c % C-x: Interactive.
973 * C-c % h: MMM Mode Keys.