# HG changeset patch # User Richard M. Stallman # Date 1107686975 0 # Node ID 1f6a9cf4499963d3d131486a9cb572cf6d320251 # Parent 654691f40a534a8dc5975416581377d3c7b88c55 (Major Mode Conventions): Mention "system abbrevs". Mode inheritance applies only when default-major-mode is nil. Clarifications. (Example Major Modes): Update Text mode and Lisp mode examples. (Minor Mode Conventions): Mention define-minor-mode at top. (Defining Minor Modes): In Hungry example, don't define C-M-DEL. (Mode Line Format): Update mode line face display info. (Properties in Mode): Mention effect of risky vars. (Imenu): Define imenu-add-to-menubar. (Font Lock Mode): Add descriptions to menu lines. (Faces for Font Lock): Add font-lock-doc-face. diff -r 654691f40a53 -r 1f6a9cf44999 lispref/modes.texi --- a/lispref/modes.texi Sun Feb 06 10:42:08 2005 +0000 +++ b/lispref/modes.texi Sun Feb 06 10:49:35 2005 +0000 @@ -235,9 +235,11 @@ @item @cindex abbrev tables in modes The mode may have its own abbrev table or may share one with other -related modes. If it has its own abbrev table, it should store this in -a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev -Tables}. +related modes. If it has its own abbrev table, it should store this +in a variable named @code{@var{modename}-mode-abbrev-table}. If the +major mode command defines any abbrevs itself, it should pass @code{t} +for the @var{system-flag} argument to @code{define-abbrev}. +@xref{Abbrev Tables}. @item The mode should specify how to do highlighting for Font Lock mode, by @@ -308,8 +310,9 @@ @end example @noindent -This tells Emacs that new buffers created while the current buffer is in -Funny mode should not inherit Funny mode. Modes such as Dired, Rmail, +This tells Emacs that new buffers created while the current buffer is +in Funny mode should not inherit Funny mode, in case +@code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail, and Buffer List use this feature. @item @@ -321,9 +324,10 @@ file that contains the mode definition. @xref{Auto Major Mode}. @item -In the documentation, you should provide a sample @code{autoload} form -and an example of how to add to @code{auto-mode-alist}, that users can -include in their init files (@pxref{Init File}). +In the comments that document the file, you should provide a sample +@code{autoload} form and an example of how to add to +@code{auto-mode-alist}, that users can include in their init files +(@pxref{Init File}). @item @cindex mode loading @@ -341,46 +345,65 @@ @smallexample @group -;; @r{Create mode-specific tables.} -(defvar text-mode-syntax-table nil - "Syntax table used while in text mode.") +;; @r{Create the syntax table for this mode.} +(defvar text-mode-syntax-table + (let ((st (make-syntax-table))) + (modify-syntax-entry ?\" ". " st) + (modify-syntax-entry ?\\ ". " st) + ;; We add `p' so that M-c on 'hello' leads to 'Hello' rather than 'hello'. + (modify-syntax-entry ?' "w p" st) + st) + "Syntax table used while in `text-mode'.") @end group +;; @r{Create the keymap for this mode.} @group -(if text-mode-syntax-table - () ; @r{Do not change the table if it is already set up.} - (setq text-mode-syntax-table (make-syntax-table)) - (modify-syntax-entry ?\" ". " text-mode-syntax-table) - (modify-syntax-entry ?\\ ". " text-mode-syntax-table) - (modify-syntax-entry ?' "w " text-mode-syntax-table)) +(defvar text-mode-map + (let ((map (make-sparse-keymap))) + (define-key map "\e\t" 'ispell-complete-word) + (define-key map "\es" 'center-line) + (define-key map "\eS" 'center-paragraph) + map) + "Keymap for `text-mode'. +Many other modes, such as `mail-mode', `outline-mode' and `indented-text-mode', +inherit all the commands defined in this map.") @end group - +@end smallexample + + Here is how the actual mode command is defined now: + +@smallexample +@group +(define-derived-mode text-mode nil "Text" + "Major mode for editing text written for humans to read. +In this mode, paragraphs are delimited only by blank or white lines. +You can thus get the full benefit of adaptive filling + (see the variable `adaptive-fill-mode'). +\\{text-mode-map} +Turning on Text mode runs the normal hook `text-mode-hook'." +@end group @group + (make-local-variable 'text-mode-variant) + (setq text-mode-variant t) + ;; @r{These two lines are a feature added recently.} + (set (make-local-variable 'require-final-newline) + mode-require-final-newline) + (set (make-local-variable 'indent-line-function) 'indent-relative)) +@end group +@end smallexample + + But here is how it was defined formerly, before +@code{define-derived-mode} existed: + +@smallexample +@group +;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} (defvar text-mode-abbrev-table nil "Abbrev table used while in text mode.") (define-abbrev-table 'text-mode-abbrev-table ()) @end group @group -(defvar text-mode-map nil ; @r{Create a mode-specific keymap.} - "Keymap for Text mode. -Many other modes, such as Mail mode, Outline mode and Indented Text mode, -inherit all the commands defined in this map.") - -(if text-mode-map - () ; @r{Do not change the keymap if it is already set up.} - (setq text-mode-map (make-sparse-keymap)) - (define-key text-mode-map "\e\t" 'ispell-complete-word) - (define-key text-mode-map "\t" 'indent-relative) - (define-key text-mode-map "\es" 'center-line) - (define-key text-mode-map "\eS" 'center-paragraph)) -@end group -@end smallexample - - This was formerly the complete major mode function definition for Text mode: - -@smallexample -@group (defun text-mode () "Major mode for editing text intended for humans to read... Special commands: \\@{text-mode-map@} @@ -396,6 +419,9 @@ (set-syntax-table text-mode-syntax-table) @end group @group + ;; @r{These four lines are absent from the current version} + ;; @r{not because this is done some other way, but rather} + ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} (make-local-variable 'paragraph-start) (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter)) (make-local-variable 'paragraph-separate) @@ -422,36 +448,48 @@ @group ;; @r{Create mode-specific table variables.} (defvar lisp-mode-syntax-table nil "") -(defvar emacs-lisp-mode-syntax-table nil "") (defvar lisp-mode-abbrev-table nil "") @end group @group -(if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table} - ; @r{if it is already set.} +(defvar emacs-lisp-mode-syntax-table + (let ((table (make-syntax-table))) (let ((i 0)) - (setq emacs-lisp-mode-syntax-table (make-syntax-table)) @end group @group - ;; @r{Set syntax of chars up to 0 to class of chars that are} + ;; @r{Set syntax of chars up to @samp{0} to say they are} ;; @r{part of symbol names but not words.} - ;; @r{(The number 0 is @code{48} in the @acronym{ASCII} character set.)} + ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} (while (< i ?0) - (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table) - (setq i (1+ i))) - @dots{} + (modify-syntax-entry i "_ " table) + (setq i (1+ i))) + ;; @r{@dots{} similar code follows for other character ranges.} +@end group +@group + ;; @r{Then set the syntax codes for characters that are special in Lisp.} + (modify-syntax-entry ? " " table) + (modify-syntax-entry ?\t " " table) + (modify-syntax-entry ?\f " " table) + (modify-syntax-entry ?\n "> " table) @end group @group - ;; @r{Set the syntax for other characters.} - (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table) - (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table) - @dots{} + ;; @r{Give CR the same syntax as newline, for selective-display.} + (modify-syntax-entry ?\^m "> " table) + (modify-syntax-entry ?\; "< " table) + (modify-syntax-entry ?` "' " table) + (modify-syntax-entry ?' "' " table) + (modify-syntax-entry ?, "' " table) +@end group @end group @group - (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table) - (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table) - @dots{})) + ;; @r{@dots{}likewise for many other characters@dots{}} + (modify-syntax-entry ?\( "() " table) + (modify-syntax-entry ?\) ")( " table) + (modify-syntax-entry ?\[ "(] " table) + (modify-syntax-entry ?\] ")[ " table)) + table)) +@end group ;; @r{Create an abbrev table for lisp-mode.} (define-abbrev-table 'lisp-mode-abbrev-table ()) @end group @@ -464,8 +502,8 @@ @smallexample @group (defun lisp-mode-variables (lisp-syntax) - (cond (lisp-syntax - (set-syntax-table lisp-mode-syntax-table))) + (when lisp-syntax + (set-syntax-table lisp-mode-syntax-table)) (setq local-abbrev-table lisp-mode-abbrev-table) @dots{} @end group @@ -504,6 +542,7 @@ (defvar shared-lisp-mode-map () "Keymap for commands shared by all sorts of Lisp modes.") +;; @r{Putting this @code{if} after the @code{defvar} is an older style.} (if shared-lisp-mode-map () (setq shared-lisp-mode-map (make-sparse-keymap)) @@ -557,6 +596,11 @@ ; @r{finds out what to describe.} (setq mode-name "Lisp") ; @r{This goes into the mode line.} (lisp-mode-variables t) ; @r{This defines various variables.} + (make-local-variable 'comment-start-skip) + (setq comment-start-skip + "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") + (make-local-variable 'font-lock-keywords-case-fold-search) + (setq font-lock-keywords-case-fold-search t) @end group @group (setq imenu-case-fold-search t) @@ -911,7 +955,8 @@ other tables. In addition, there are several conventions that are specific to -minor modes. +minor modes. (The easiest way to follow all the conventions is to use +the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.) @itemize @bullet @item @@ -1001,7 +1046,7 @@ If just setting the variable is not sufficient to enable the mode, you should also specify a @code{:set} method which enables the mode by -invoke the mode command. Note in the variable's documentation string that +invoking the mode command. Note in the variable's documentation string that setting the variable other than via Custom may not take effect. Also mark the definition with an autoload cookie (@pxref{Autoload}), @@ -1124,11 +1169,7 @@ ;; The indicator for the mode line. " Hungry" ;; The minor mode bindings. - '(("\C-\^?" . hungry-electric-delete) - ("\C-\M-\^?" - . (lambda () - (interactive) - (hungry-electric-delete t)))) + '(("\C-\^?" . hungry-electric-delete)) :group 'hunger) @end smallexample @@ -1137,10 +1178,10 @@ @code{hungry-mode} to toggle it, a variable named @code{hungry-mode} which indicates whether the mode is enabled, and a variable named @code{hungry-mode-map} which holds the keymap that is active when the -mode is enabled. It initializes the keymap with key bindings for -@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}. It puts the variable -@code{hungry-mode} into custom group @code{hunger}. There are no -@var{body} forms---many minor modes don't need any. +mode is enabled. It initializes the keymap with a key binding for +@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into +custom group @code{hunger}. There are no @var{body} forms---many +minor modes don't need any. Here's an equivalent way to write it: @@ -1216,8 +1257,9 @@ and the frame title. @end defun - The mode line is usually displayed in inverse video; see -@code{mode-line-inverse-video} in @ref{Inverse Video}. + The selected window's mode line is usually displayed in a different +color using the face @code{mode-line}. Other windows' mode lines +appear in the face @code{mode-line-inactive} instead. @xref{Faces}. A window that is just one line tall does not display either a mode line or a header line, even if the variables call for one. A window @@ -1703,6 +1745,13 @@ effect, since it is impossible to move point into the mode line. This keymap can only take real effect for mouse clicks. + When the mode line refers to a variable which does not have a +non-@code{nil} @code{risky-local-variable} property, any text +properties given or specified within that variable's values are +ignored. This is because such properties could otherwise specify +functions to be called, and those functions could come from file +local variables. + @node Header Lines @subsection Window Header Lines @cindex header line (of a window) @@ -1770,11 +1819,18 @@ directly to that location in the buffer. Imenu works by constructing a buffer index which lists the names and buffer positions of the definitions, or other named portions of the buffer; then the user can -choose one of them and move point to it. The user-level commands for -using Imenu are described in the Emacs Manual (@pxref{Imenu,, Imenu, -emacs, the Emacs Manual}). This section explains how to customize -Imenu's method of finding definitions or buffer portions for a -particular major mode. +choose one of them and move point to it. Major modes can add a menu +bar item to use Imenu using @code{imenu-add-to-menubar}. + +@defun imenu-add-to-menubar name +This function defines a local menu bar item named @var{name} +to run Imenu. +@end defun + + The user-level commands for using Imenu are described in the Emacs +Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section +explains how to customize Imenu's method of finding definitions or +buffer portions for a particular major mode. The usual and simplest way is to set the variable @code{imenu-generic-expression}: @@ -1967,13 +2023,16 @@ (@pxref{Faces for Font Lock}). Search-based fontification follows. @menu -* Font Lock Basics:: -* Search-based Fontification:: -* Other Font Lock Variables:: -* Levels of Font Lock:: -* Precalculated Fontification:: -* Faces for Font Lock:: -* Syntactic Font Lock:: +* Font Lock Basics:: Overview of customizing Font Lock. +* Search-based Fontification:: Fontification based on regexps. +* Other Font Lock Variables:: Additional customization facilities. +* Levels of Font Lock:: Each mode can define alternative levels + so that the user can select more or less. +* Precalculated Fontification:: How Lisp programs that produce the buffer + contents can also specify how to fontify it. +* Faces for Font Lock:: Special faces specifically for Font Lock. +* Syntactic Font Lock:: Defining character syntax based on context + using the Font Lock mechanism. @end menu @node Font Lock Basics @@ -2357,7 +2416,7 @@ @node Precalculated Fontification @subsection Precalculated Fontification -In addition to using @code{font-lock-defaults} for search-based + In addition to using @code{font-lock-defaults} for search-based fontification, you may use the special character property @code{font-lock-face} (@pxref{Special Properties}). This property acts just like the explicit @code{face} property, but its activation @@ -2394,6 +2453,10 @@ @vindex font-lock-comment-face Used (typically) for comments. +@item font-lock-doc-face +@vindex font-lock-doc-face +Used (typically) for documentation strings in the code. + @item font-lock-string-face @vindex font-lock-string-face Used (typically) for string constants.