diff options
Diffstat (limited to 'doc/lispref/modes.texi')
| -rw-r--r-- | doc/lispref/modes.texi | 142 |
1 files changed, 84 insertions, 58 deletions
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index ce7727b87eb..d9caeab3bc3 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -861,6 +861,13 @@ abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} if @var{parent} is @code{nil}. (Again, a @code{nil} value is @emph{not} equivalent to not specifying this keyword.) +@item :interactive +Modes are interactive commands by default. If you specify a +@code{nil} value, the mode defined here won't be interactive. This is +useful for modes that are never meant to be activated by users +manually, but are only supposed to be used in some specially-formatted +buffer. + @item :group If this is specified, the value should be the customization group for this mode. (Not all major modes have one.) The command @@ -1454,6 +1461,16 @@ used only with Diff mode. other minor modes in effect. It should be possible to activate and deactivate minor modes in any order. +@defvar local-minor-modes +This buffer-local variable lists the currently enabled minor modes in +the current buffer, and is a list of symbols. +@end defvar + +@defvar global-minor-modes +This variable lists the currently enabled global minor modes, and is a +list of symbols. +@end defvar + @defvar minor-mode-list The value of this variable is a list of all minor mode commands. @end defvar @@ -1643,7 +1660,7 @@ reserved for users. @xref{Key Binding Conventions}. The macro @code{define-minor-mode} offers a convenient way of implementing a mode in one self-contained definition. -@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} +@defmac define-minor-mode mode doc keyword-args@dots{} body@dots{} This macro defines a new minor mode whose name is @var{mode} (a symbol). It defines a command named @var{mode} to toggle the minor mode, with @var{doc} as its documentation string. @@ -1658,41 +1675,12 @@ If @var{doc} is @code{nil}, the macro supplies a default documentation string explaining the above. By default, it also defines a variable named @var{mode}, which is set to -@code{t} or @code{nil} by enabling or disabling the mode. The variable -is initialized to @var{init-value}. Except in unusual circumstances -(see below), this value must be @code{nil}. - -The string @var{lighter} says what to display in the mode line -when the mode is enabled; if it is @code{nil}, the mode is not displayed -in the mode line. - -The optional argument @var{keymap} specifies the keymap for the minor -mode. If non-@code{nil}, it should be a variable name (whose value is -a keymap), a keymap, or an alist of the form - -@example -(@var{key-sequence} . @var{definition}) -@end example - -@noindent -where each @var{key-sequence} and @var{definition} are arguments -suitable for passing to @code{define-key} (@pxref{Changing Key -Bindings}). If @var{keymap} is a keymap or an alist, this also -defines the variable @code{@var{mode}-map}. +@code{t} or @code{nil} by enabling or disabling the mode. -The above three arguments @var{init-value}, @var{lighter}, and -@var{keymap} can be (partially) omitted when @var{keyword-args} are -used. The @var{keyword-args} consist of keywords followed by +The @var{keyword-args} consist of keywords followed by corresponding values. A few keywords have special meanings: @table @code -@item :group @var{group} -Custom group name to use in all generated @code{defcustom} forms. -Defaults to @var{mode} without the possible trailing @samp{-mode}. -@strong{Warning:} don't use this default group name unless you have -written a @code{defgroup} to define that group properly. @xref{Group -Definitions}. - @item :global @var{global} If non-@code{nil}, this specifies that the minor mode should be global rather than buffer-local. It defaults to @code{nil}. @@ -1702,19 +1690,34 @@ One of the effects of making a minor mode global is that the through the Customize interface turns the mode on and off, and its value can be saved for future Emacs sessions (@pxref{Saving Customizations,,, emacs, The GNU Emacs Manual}. For the saved -variable to work, you should ensure that the @code{define-minor-mode} -form is evaluated each time Emacs starts; for packages that are not -part of Emacs, the easiest way to do this is to specify a -@code{:require} keyword. +variable to work, you should ensure that the minor mode function +is available each time Emacs starts; usually this is done by +marking the @code{define-minor-mode} form as autoloaded. @item :init-value @var{init-value} -This is equivalent to specifying @var{init-value} positionally. +This is the value to which the @var{mode} variable is initialized. +Except in unusual circumstances (see below), this value must be +@code{nil}. @item :lighter @var{lighter} -This is equivalent to specifying @var{lighter} positionally. +The string @var{lighter} says what to display in the mode line +when the mode is enabled; if it is @code{nil}, the mode is not displayed +in the mode line. @item :keymap @var{keymap} -This is equivalent to specifying @var{keymap} positionally. +The optional argument @var{keymap} specifies the keymap for the minor +mode. If non-@code{nil}, it should be a variable name (whose value is +a keymap), a keymap, or an alist of the form + +@example +(@var{key-sequence} . @var{definition}) +@end example + +@noindent +where each @var{key-sequence} and @var{definition} are arguments +suitable for passing to @code{define-key} (@pxref{Changing Key +Bindings}). If @var{keymap} is a keymap or an alist, this also +defines the variable @code{@var{mode}-map}. @item :variable @var{place} This replaces the default variable @var{mode}, used to store the state @@ -1725,11 +1728,17 @@ anything that can be used with the @code{setf} function (@pxref{Generalized Variables}). @var{place} can also be a cons @code{(@var{get} . @var{set})}, where @var{get} is an expression that returns the current state, -and @var{set} is a function of one argument (a state) that sets it. +and @var{set} is a function of one argument (a state) which should be +assigned to @var{place}. @item :after-hook @var{after-hook} This defines a single Lisp form which is evaluated after the mode hooks have run. It should not be quoted. + +@item :interactive @var{value} +Minor modes are interactive commands by default. If @var{value} is +@code{nil}, this is inhibited. If @var{value} is a list of symbols, +it's used to say which major modes this minor mode is useful in. @end table Any other keyword arguments are passed directly to the @@ -2243,16 +2252,15 @@ number. The format used to display column numbers when @code{column-number-mode} (@pxref{Optional Mode Line,,, emacs, The GNU Emacs Manual}) is switched on. @samp{%c} in the format will be -replaced with the column number, and this is zero-based if -@code{column-number-indicator-zero-based} is non-@code{nil}, and -one-based if @code{column-number-indicator-zero-based} is @code{nil}. +replaced with a zero-based column number, and @samp{%C} will be +replaced with a one-based column number. @end defvar @defvar mode-line-position-column-line-format The format used to display column numbers when both @code{line-number-mode} and @code{column-number-mode} are switched on. -See the previous two variables for the meaning of the @samp{%l} and -@samp{%c} format specs. +See the previous two variables for the meaning of the @samp{%l}, +@samp{%c} and @samp{%C} format specs. @end defvar @defvar minor-mode-alist @@ -2279,11 +2287,14 @@ enabled separately in each buffer. @defvar global-mode-string This variable holds a mode line construct that, by default, appears in -the mode line just after the @code{which-function-mode} minor mode if set, -else after @code{mode-line-modes}. The command @code{display-time} sets +the mode line just after the @code{which-function-mode} minor mode if +set, else after @code{mode-line-modes}. Elements that are added to +this construct should normally end in a space (to ensure that +consecutive @code{global-mode-string} elements display properly). For +instance, the command @code{display-time} sets @code{global-mode-string} to refer to the variable -@code{display-time-string}, which holds a string containing the time and -load information. +@code{display-time-string}, which holds a string containing the time +and load information. The @samp{%M} construct substitutes the value of @code{global-mode-string}, but that is obsolete, since the variable is @@ -2977,10 +2988,6 @@ highlighted (instead of the entire text that @var{matcher} matched). ("fu\\(bar\\)" . 1) @end example -If you use @code{regexp-opt} to produce the regular expression -@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp -Functions}) to calculate the value for @var{subexp}. - @item (@var{matcher} . @var{facespec}) In this kind of element, @var{facespec} is an expression whose value specifies the face to use for highlighting. In the simplest case, @@ -2996,7 +3003,8 @@ name. However, @var{facespec} can also evaluate to a list of this form: @example -(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) +(@var{subexp} +(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})) @end example @noindent @@ -3225,8 +3233,7 @@ set by means of @var{other-vars} in @code{font-lock-defaults} @defvar font-lock-mark-block-function If this variable is non-@code{nil}, it should be a function that is called with no arguments, to choose an enclosing range of text for -refontification for the command @kbd{M-o M-o} -(@code{font-lock-fontify-block}). +refontification for the command @kbd{M-x font-lock-fontify-block}. The function should report its choice by placing the region around it. A good choice is a range of text large enough to give proper results, @@ -3438,9 +3445,17 @@ for string constants. @item font-lock-doc-face @vindex font-lock-doc-face -for documentation strings in the code. This inherits, by default, from +for documentation embedded in program code inside specially-formed +comments or strings. This face inherits, by default, from @code{font-lock-string-face}. +@item font-lock-doc-markup-face +@vindex font-lock-doc-markup-face +for mark-up elements in text using @code{font-lock-doc-face}. +It is typically used for the mark-up constructs in documentation embedded +in program code, following conventions such as Haddock, Javadoc or Doxygen. +This face inherits, by default, from @code{font-lock-constant-face}. + @item font-lock-negation-char-face @vindex font-lock-negation-char-face for easily-overlooked negation characters. @@ -3547,7 +3562,7 @@ which will instruct font-lock not to start or end the scan in the middle of the construct. @end itemize - There are three ways to do rehighlighting of multiline constructs: + There are several ways to do rehighlighting of multiline constructs: @itemize @item @@ -3569,6 +3584,17 @@ This works only if @code{jit-lock-contextually} is used, and with the same delay before rehighlighting, but like @code{font-lock-multiline}, it also handles the case where highlighting depends on subsequent lines. +@item +If parsing the @emph{syntax} of a construct depends on it being parsed in one +single chunk, you can add the @code{syntax-multiline} text property +over the construct in question. The most common use for this is when +the syntax property to apply to @samp{FOO} depend on some later text +@samp{BAR}: By placing this text property over the whole of +@samp{FOO...BAR}, you make sure that any change of @samp{BAR} will +also cause the syntax property of @samp{FOO} to be recomputed. +Note: For this to work, the mode needs to add +@code{syntax-propertize-multiline} to +@code{syntax-propertize-extend-region-functions}. @end itemize @menu |