[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] master d856bc2 106/433: Wrote about global classes, highlight, m
From: |
Dmitry Gutov |
Subject: |
[elpa] master d856bc2 106/433: Wrote about global classes, highlight, mode line, and hooks. |
Date: |
Thu, 15 Mar 2018 19:43:45 -0400 (EDT) |
branch: master
commit d856bc27b2b47ad41786601966cce992b4b0dbf2
Author: mas <mas>
Commit: mas <mas>
Wrote about global classes, highlight, mode line, and hooks.
---
mmm.texinfo | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 140 insertions(+), 15 deletions(-)
diff --git a/mmm.texinfo b/mmm.texinfo
index 51560e2..7544923 100644
--- a/mmm.texinfo
+++ b/mmm.texinfo
@@ -100,6 +100,7 @@ Customizing MMM Mode
* 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
@@ -133,6 +134,7 @@ 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
@@ -400,7 +402,7 @@ off) manually with @kbd{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.
address@hidden Command mmm-mode arg
address@hidden Command mmm-mode @var{arg}
Toggle the state of MMM Mode in the current buffer. If @var{arg} is
supplied, turn MMM Mode on if and only if @var{arg} is positive.
@end deffn
@@ -512,6 +514,7 @@ 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.
@end menu
@@ -533,7 +536,7 @@ desired value of @code{mmm-classes} for the file in
question. It can
also be done with a local variables list at the end of the file.
address@hidden Mode-Ext Classes, , File Classes, Selecting Classes
address@hidden Mode-Ext Classes, Global Classes, File Classes, Selecting Classes
@comment node-name, next, previous, up
@section Submode Classes Associated with Modes and Extensions
@@ -559,7 +562,7 @@ buffers even if there are no actual submode classes being
applied.
@xref{Global Mode}.
@end defopt
address@hidden mmm-add-mode-ext-class mode ext class
address@hidden mmm-add-mode-ext-class @var{mode} @var{ext} @var{class}
This function adds an element to @code{mmm-mode-ext-classes-alist},
associating the submode class @var{class} with the major mode @var{mode}
and extension @var{ext}.
@@ -571,6 +574,38 @@ backward compatibility.
@end defun
address@hidden Global Classes, , Mode-Ext Classes, Selecting Classes
address@hidden node-name, next, previous, up
address@hidden 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
address@hidden buffers in which MMM Mode is enabled.
+
address@hidden 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 @code{(universal)}.
address@hidden defopt
+
+The default global class is the ``universal class'', which is defined in
+the file @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 @address@hidden@address@hidden ... @{%/@address@hidden, where
address@hidden should be the name of the major mode, with or without the
+customary @samp{-mode} suffix: for example, both @samp{cperl} and
address@hidden are acceptable.
+
+The universal class also defines an insertion key, @samp{/}, which
+prompts for the submode to use. @xref{Insertion}. The universal class
+is most useful when @code{mmm-global-mode} is set to @code{t};
address@hidden Mode}.
+
+
@node Insertion, Re-parsing, Selecting Classes, Top
@comment node-name, next, previous, up
@chapter Inserting new submode regions
@@ -659,12 +694,11 @@ Describe @code{mmm-parse-buffer}, @code{mmm-parse-region},
@cindex interactive mmm-ification, history of
There are several commands you can use to create submode regions
-interactively, rather than by applying a submode class to a buffer. I
-find these commands (in particular, @code{mmm-ify-region}) to be most useful
-when I am editing a file or email message and want to include a snippet
-of code in some other language. For example, when I email someone a few
-lines of elisp code, I often put those lines in Emacs-Lisp mode to get
-the indentation nice and make sure the syntax is correct.
+interactively, rather than by applying a submode class to a buffer.
+These commands (in particular, @code{mmm-ify-region}), can be useful
+when editing a file or email message containing a snippet of code in
+some other language. Also see @ref{Global Classes}, for an alternate
+approach to the same problem.
@table @kbd
@item C-c % C-r
@@ -810,31 +844,122 @@ buffers:
@cindex customizing submode faces
@cindex default submode face
-[add stuff here]
+By default, MMM Mode highlights all submode regions with a light gray
+background color. You can change the color of the highlight, or turn it
+off entirely. You might want to do this if you don't like how it looks,
+or if you want to use background colors for font-lock (the submode
+highlight, if present, overrides any font-lock background coloring).
+The highlight is done with the face @code{mmm-default-submode-face}
+(@pxref{Faces, , emacs, The Emacs Manual}) which can be customized,
+either through the Emacs ``customize'' interface or using direct Lisp
+commands. To turn the highlight off, add the following line to your
address@hidden file:
+
address@hidden
+(set-face-background 'mmm-default-submode-face nil)
address@hidden lisp
+
+To set the highlight color, a similar syntax can be used:
+
address@hidden
+(set-face-background 'mmm-default-submode-face "blue")
address@hidden lisp
+
+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.
-This can conflict with font-lock, if font-lock wants to use a background
-color. In such cases, the submode face takes precedence. If this bothers
-you, you can turn it off.
@node Mode Line, Key Bindings, Submode Faces, Top
@comment node-name, next, previous, up
@chapter Customizing the Mode Line Display
+By default, when in a submode region, MMM Mode changes the section of
+the mode line (@pxref{Mode Line, , , emacs, The Emacs Manual}) that
+normally displays the major mode name---for example, @samp{HTML}---to
+instead show both the dominant major mode and the currently active
+submode---for example, @samp{HTML[CPerl]}. You can change this format,
+however.
+
address@hidden mmm-submode-mode-line-format
+The value of this variable should be a string containing one or both of
+the escape sequences @samp{~M} and @samp{~m}. The string displayed in
+the major mode section of the mode line when in a submode is obtained by
+replacing all occurrences of @samp{~M} with the dominant major mode name
+and @samp{~m} with the currently active submode name. For example, to
+display only the currently active submode, set this variable to
address@hidden The default value is @samp{~M[~m]}.
address@hidden defopt
+
+The MMM minor mode also normally displays the string @samp{MMM} in the
+minor mode section of the mode line to indicate when it is active. You
+can customize or disable this as well.
+
address@hidden 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.
address@hidden defopt
+
@node Key Bindings, Local Variables, Mode Line, Top
@comment node-name, next, previous, up
@chapter Customizing the MMM Mode Key Bindings
address@hidden Local Variables, Hooks, Key Bindings, Top
+
address@hidden Local Variables, Changing Classes, Key Bindings, Top
@comment node-name, next, previous, up
@chapter Changing Saved Local Variables
address@hidden Hooks, Mason, Local Variables, Top
+
address@hidden Changing Classes, Hooks, Local Variables, Top
address@hidden node-name, next, previous, up
address@hidden Changing the Supplied Submode Classes
+
+
+
+
address@hidden Hooks, Mason, Changing Classes, Top
@comment node-name, next, previous, up
@chapter Hooks Provided by MMM Mode
+MMM Mode defines several hook variables (@pxref{Hooks, , , emacs, The
+Emacs Manual}) which are run at different times. The most often used is
address@hidden which is described in @ref{Major Mode Hook},
+but there are a couple others.
+
address@hidden mmm-mode-hook
+This normal hook is run whenever MMM Mode is enabled in a buffer.
address@hidden defvar
+
address@hidden address@hidden
+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.
address@hidden defvar
+
address@hidden address@hidden
+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.
address@hidden defvar
+
address@hidden address@hidden
+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.
address@hidden defvar
+
+Submode classes also have a @code{: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 @code{mmm-set-class-parameter};
address@hidden Classes}.
+
@node Mason, Eval-Elisp, Hooks, Top
@comment node-name, next, previous, up
- [elpa] master 7a12efa 111/433: Added MASON_VERSION variable to keep track of that., (continued)
- [elpa] master 7a12efa 111/433: Added MASON_VERSION variable to keep track of that., Dmitry Gutov, 2018/03/15
- [elpa] master e7da5c1 117/433: # Updated., Dmitry Gutov, 2018/03/15
- [elpa] master 88d1d46 115/433: (mmm-univ-get-mode): Signaled error on non-fboundp modes., Dmitry Gutov, 2018/03/15
- [elpa] master 752288f 113/433: Added `mmm-no-matching-submode' error signal., Dmitry Gutov, 2018/03/15
- [elpa] master 3ee92f7 091/433: Moved commentary code to README.Mason., Dmitry Gutov, 2018/03/15
- [elpa] master efe3dbf 092/433: Wrote more about Mason., Dmitry Gutov, 2018/03/15
- [elpa] master e632aec 105/433: Limited matches to letter/dash strings that are fboundp., Dmitry Gutov, 2018/03/15
- [elpa] master b73a727 018/433: Added to CVS (formerly not under RCS)., Dmitry Gutov, 2018/03/15
- [elpa] master 28e978c 118/433: (mmm-ify-by-class): Added completion on all defined classes., Dmitry Gutov, 2018/03/15
- [elpa] master 34fbbd5 120/433: # Updated docstring., Dmitry Gutov, 2018/03/15
- [elpa] master d856bc2 106/433: Wrote about global classes, highlight, mode line, and hooks.,
Dmitry Gutov <=
- [elpa] master 3cd5dcb 123/433: Changed output name from `mmm' to `mmm-mode'., Dmitry Gutov, 2018/03/15
- [elpa] master a8a9d33 122/433: Updated file-variables class to handle prefixes., Dmitry Gutov, 2018/03/15
- [elpa] master 8fd343b 119/433: # Updated folding marks., Dmitry Gutov, 2018/03/15
- [elpa] master 239284f 124/433: # Updated, Dmitry Gutov, 2018/03/15
- [elpa] master c74eeb5 125/433: # Updated email address, Dmitry Gutov, 2018/03/15
- [elpa] master ee185fa 127/433: # Removed a duplicate entry, Dmitry Gutov, 2018/03/15
- [elpa] master e0f50ca 121/433: Wrote File Variables submode class for the new syntax., Dmitry Gutov, 2018/03/15
- [elpa] master dbf0649 126/433: # Updated for SourceForge, Dmitry Gutov, 2018/03/15
- [elpa] master 644b5be 131/433: (here-doc): Updated to use new front-offset values., Dmitry Gutov, 2018/03/15
- [elpa] master 20ae2f5 139/433: # Updated docstring., Dmitry Gutov, 2018/03/15