home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / elisp / elisp-16 < prev    next >
Encoding:
GNU Info File  |  1993-05-31  |  45.8 KB  |  1,100 lines
  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.  
  4.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  5. Emacs Version 19.
  6.  
  7.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  8. Cambridge, MA 02139 USA
  9.  
  10.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Foundation.
  25.  
  26. 
  27. File: elisp,  Node: Major Mode Conventions,  Next: Example Major Modes,  Prev: Major Modes,  Up: Major Modes
  28.  
  29. Major Mode Conventions
  30. ----------------------
  31.  
  32.    The code for existing major modes follows various coding conventions,
  33. including conventions for local keymap and syntax table initialization,
  34. global names, and hooks.  Please keep these conventions in mind when you
  35. create a new major mode:
  36.  
  37.    * Define a command whose name ends in `-mode', with no arguments,
  38.      that switches to the new mode in the current buffer.  This command
  39.      should set up the keymap, syntax table, and local variables in an
  40.      existing buffer without changing the buffer's text.
  41.  
  42.    * Write a documentation string for this command which describes the
  43.      special commands available in this mode.  `C-h m'
  44.      (`describe-mode') will print this.
  45.  
  46.      The documentation string may include the special documentation
  47.      substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
  48.      enable the documentation to adapt automatically to the user's own
  49.      key bindings.  *Note Keys in Documentation::.  The `describe-mode'
  50.      function replaces these special documentation substrings with
  51.      their current meanings.  *Note Accessing Documentation::.
  52.  
  53.    * The major mode command should set the variable `major-mode' to the
  54.      major mode command symbol.  This is how `describe-mode' discovers
  55.      which documentation to print.
  56.  
  57.    * The major mode command should set the variable `mode-name' to the
  58.      "pretty" name of the mode, as a string.  This appears in the mode
  59.      line.
  60.  
  61.    * Since all global names are in the same name space, all the global
  62.      variables, constants, and functions that are part of the mode
  63.      should have names that start with the major mode name (or with an
  64.      abbreviation of it if the name is long).  *Note Style Tips::.
  65.  
  66.    * The major mode should usually have its own keymap, which is used
  67.      as the local keymap in all buffers in that mode.  The major mode
  68.      function should call `use-local-map' to install this local map.
  69.      *Note Active Keymaps::, for more information.
  70.  
  71.      This keymap should be kept in a global variable named
  72.      `MODENAME-mode-map'.  Normally the library that defines the mode
  73.      sets this variable.  Use `defvar' to set the variable, so that it
  74.      is not reinitialized if it already has a value.  (Such
  75.      reinitialization could discard customizations made by the user.)
  76.  
  77.    * The mode may have its own syntax table or may share one with other
  78.      related modes.  If it has its own syntax table, it should store
  79.      this in a variable named `MODENAME-mode-syntax-table'.  The reasons
  80.      for this are the same as for using a keymap variable.  *Note
  81.      Syntax Tables::.
  82.  
  83.    * The mode may have its own abbrev table or may share one with other
  84.      related modes.  If it has its own abbrev table, it should store
  85.      this in a variable named `MODENAME-mode-abbrev-table'.  *Note
  86.      Abbrev Tables::.
  87.  
  88.    * To give a variable a buffer-local binding, use
  89.      `make-local-variable' in the major mode command, not
  90.      `make-variable-buffer-local'.  The latter function would make the
  91.      variable local to every buffer in which it is subsequently set,
  92.      which would affect buffers that do not use this mode.  It is
  93.      undesirable for a mode to have such global effects.  *Note
  94.      Buffer-Local Variables::.
  95.  
  96.    * If hooks are appropriate for the mode, the major mode command
  97.      should run the hooks after completing all other initialization so
  98.      the user may further customize any of the settings.  *Note Hooks::.
  99.  
  100.    * If this mode is appropriate only for specially-prepared text, then
  101.      the major mode command symbol should have a property named
  102.      `mode-class' with value `special', put on as follows:
  103.  
  104.           (put 'funny-mode 'mode-class 'special)
  105.  
  106.      This tells Emacs that new buffers created while the current buffer
  107.      has Funny mode should not inherit Funny mode.  Modes such as
  108.      Dired, Rmail, and Buffer List use this feature.
  109.  
  110.    * If it is desirable that Emacs use the new mode by default after
  111.      visiting files with certain recognizable names, add an element to
  112.      `auto-mode-alist' to select the mode for those file names.  If you
  113.      define the mode command to autoload, you should add this element
  114.      in the same file that calls `autoload'.  Otherwise, it is
  115.      sufficient to add the element in the file that contains the mode
  116.      definition.  *Note Auto Major Mode::.
  117.  
  118.    * In the documentation, you should provide a sample `autoload' form
  119.      and an example of how to add to `auto-mode-alist', that users can
  120.      include in their `.emacs' files.
  121.  
  122.    * The top level forms in the file defining the mode should be
  123.      written so that they may be evaluated more than once without
  124.      adverse consequences.  Even if you never load the file more than
  125.      once, someone else will.
  126.  
  127. 
  128. File: elisp,  Node: Example Major Modes,  Next: Auto Major Mode,  Prev: Major Mode Conventions,  Up: Major Modes
  129.  
  130. Major Mode Examples
  131. -------------------
  132.  
  133.    Text mode is perhaps the simplest mode besides Fundamental mode.
  134. Here are excerpts from  `text-mode.el' that illustrate many of the
  135. conventions listed above:
  136.  
  137.      ;; Create mode-specific tables.
  138.      (defvar text-mode-syntax-table nil
  139.        "Syntax table used while in text mode.")
  140.  
  141.      (if text-mode-syntax-table
  142.          ()              ; Do not change the table if it is already set up.
  143.        (setq text-mode-syntax-table (make-syntax-table))
  144.        (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
  145.        (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
  146.        (modify-syntax-entry ?' "w   " text-mode-syntax-table))
  147.  
  148.      (defvar text-mode-abbrev-table nil
  149.        "Abbrev table used while in text mode.")
  150.      (define-abbrev-table 'text-mode-abbrev-table ())
  151.  
  152.      (defvar text-mode-map nil)   ; Create a mode-specific keymap.
  153.      
  154.      (if text-mode-map
  155.          ()              ; Do not change the keymap if it is already set up.
  156.        (setq text-mode-map (make-sparse-keymap))
  157.        (define-key text-mode-map "\t" 'tab-to-tab-stop)
  158.        (define-key text-mode-map "\es" 'center-line)
  159.        (define-key text-mode-map "\eS" 'center-paragraph))
  160.  
  161.    Here is the complete major mode function definition for Text mode:
  162.  
  163.      (defun text-mode ()
  164.        "Major mode for editing text intended for humans to read.
  165.       Special commands: \\{text-mode-map}
  166.  
  167.      Turning on text-mode runs the hook `text-mode-hook'."
  168.        (interactive)
  169.        (kill-all-local-variables)
  170.  
  171.      (use-local-map text-mode-map)     ; This provides the local keymap.
  172.        (setq mode-name "Text")           ; This name goes into the mode line.
  173.        (setq major-mode 'text-mode)      ; This is how `describe-mode'
  174.                                          ;   finds the doc string to print.
  175.        (setq local-abbrev-table text-mode-abbrev-table)
  176.        (set-syntax-table text-mode-syntax-table)
  177.        (run-hooks 'text-mode-hook))      ; Finally, this permits the user to
  178.                                          ;   customize the mode with a hook.
  179.  
  180.    The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
  181. Interaction mode) have more features than Text mode and the code is
  182. correspondingly more complicated.  Here are excerpts from
  183. `lisp-mode.el' that illustrate how these modes are written.
  184.  
  185.      ;; Create mode-specific table variables.
  186.      (defvar lisp-mode-syntax-table nil "")
  187.      (defvar emacs-lisp-mode-syntax-table nil "")
  188.      (defvar lisp-mode-abbrev-table nil "")
  189.  
  190.      (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
  191.                                             ;   if it is already set.
  192.          (let ((i 0))
  193.            (setq emacs-lisp-mode-syntax-table (make-syntax-table))
  194.  
  195.      ;; Set syntax of chars up to 0 to class of chars that are
  196.            ;;   part of symbol names but not words.
  197.            ;;   (The number 0 is `48' in the ASCII character set.)
  198.            (while (< i ?0)
  199.              (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
  200.              (setq i (1+ i)))
  201.            ...
  202.  
  203.      ;; Set the syntax for other characters.
  204.            (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
  205.            (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
  206.            ...
  207.  
  208.      (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
  209.            (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
  210.            ...))
  211.      ;; Create an abbrev table for lisp-mode.
  212.      (define-abbrev-table 'lisp-mode-abbrev-table ())
  213.  
  214.    Much code is shared among the three Lisp modes.  The following
  215. function sets various variables; it is called by each of the major Lisp
  216. mode functions:
  217.  
  218.      (defun lisp-mode-variables (lisp-syntax)
  219.        ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
  220.        ;;   and `t' in the other two Lisp modes.
  221.        (cond (lisp-syntax
  222.               (if (not lisp-mode-syntax-table)
  223.                   ;; The Emacs Lisp mode syntax table always exists, but
  224.                   ;;   the Lisp Mode syntax table is created the first time a
  225.                   ;;   mode that needs it is called.  This is to save space.
  226.  
  227.      (progn (setq lisp-mode-syntax-table
  228.                             (copy-syntax-table emacs-lisp-mode-syntax-table))
  229.                          ;; Change some entries for Lisp mode.
  230.                          (modify-syntax-entry ?\| "\"   "
  231.                                               lisp-mode-syntax-table)
  232.                          (modify-syntax-entry ?\[ "_   "
  233.                                               lisp-mode-syntax-table)
  234.                          (modify-syntax-entry ?\] "_   "
  235.                                               lisp-mode-syntax-table)))
  236.  
  237.      (set-syntax-table lisp-mode-syntax-table)))
  238.        (setq local-abbrev-table lisp-mode-abbrev-table)
  239.        ...)
  240.  
  241.    Functions such as `forward-paragraph' use the value of the
  242. `paragraph-start' variable.  Since Lisp code is different from ordinary
  243. text, the `paragraph-start' variable needs to be set specially to
  244. handle Lisp.  Also, comments are indented in a special fashion in Lisp
  245. and the Lisp modes need their own mode-specific
  246. `comment-indent-function'.  The code to set these variables is the rest
  247. of `lisp-mode-variables'.
  248.  
  249.      (make-local-variable 'paragraph-start)
  250.        (setq paragraph-start (concat "^$\\|" page-delimiter))
  251.        ...
  252.  
  253.      (make-local-variable 'comment-indent-function)
  254.        (setq comment-indent-function 'lisp-comment-indent))
  255.  
  256.    Each of the different Lisp modes has a slightly different keymap.
  257. For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
  258. Lisp modes do not.  However, all Lisp modes have some commands in
  259. common.  The following function adds these common commands to a given
  260. keymap.
  261.  
  262.      (defun lisp-mode-commands (map)
  263.        (define-key map "\e\C-q" 'indent-sexp)
  264.        (define-key map "\177" 'backward-delete-char-untabify)
  265.        (define-key map "\t" 'lisp-indent-line))
  266.  
  267.    Here is an example of using `lisp-mode-commands' to initialize a
  268. keymap, as part of the code for Emacs Lisp mode.  First we declare a
  269. variable with `defvar' to hold the mode-specific keymap.  When this
  270. `defvar' executes, it sets the variable to `nil' if it was void.  Then
  271. we set up the keymap if the variable is `nil'.
  272.  
  273.    This code avoids changing the keymap or the variable if it is already
  274. set up.  This lets the user customize the keymap if he or she so wishes.
  275.  
  276.      (defvar emacs-lisp-mode-map () "")
  277.      
  278.      (if emacs-lisp-mode-map
  279.          ()
  280.        (setq emacs-lisp-mode-map (make-sparse-keymap))
  281.        (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
  282.        (lisp-mode-commands emacs-lisp-mode-map))
  283.  
  284.    Finally, here is the complete major mode function definition for
  285. Emacs Lisp mode.
  286.  
  287.      (defun emacs-lisp-mode ()
  288.        "Major mode for editing Lisp code to run in Emacs.
  289.      Commands:
  290.      Delete converts tabs to spaces as it moves back.
  291.      Blank lines separate paragraphs.  Semicolons start comments.
  292.      \\{emacs-lisp-mode-map}
  293.  
  294.      Entry to this mode runs the hook `emacs-lisp-mode-hook'."
  295.        (interactive)
  296.        (kill-all-local-variables)
  297.        (use-local-map emacs-lisp-mode-map)    ; This provides the local keymap.
  298.        (set-syntax-table emacs-lisp-mode-syntax-table)
  299.  
  300.      (setq major-mode 'emacs-lisp-mode)     ; This is how `describe-mode'
  301.                                               ;   finds out what to describe.
  302.        (setq mode-name "Emacs-Lisp")          ; This goes into the mode line.
  303.        (lisp-mode-variables nil)              ; This define various variables.
  304.        (run-hooks 'emacs-lisp-mode-hook))     ; This permits the user to use a
  305.                                               ;   hook to customize the mode.
  306.  
  307. 
  308. File: elisp,  Node: Auto Major Mode,  Next: Mode Help,  Prev: Example Major Modes,  Up: Major Modes
  309.  
  310. How Emacs Chooses a Major Mode
  311. ------------------------------
  312.  
  313.    Based on information in the file name or in the file itself, Emacs
  314. automatically selects a major mode for the new buffer when a file is
  315. visited.
  316.  
  317.  - Command: fundamental-mode
  318.      Fundamental mode is a major mode that is not specialized for
  319.      anything in particular.  Other major modes are defined in effect
  320.      by comparison with this one--their definitions say what to change,
  321.      starting from Fundamental mode.  The `fundamental-mode' function
  322.      does *not* run any hooks, so it is not readily customizable.
  323.  
  324.  - Command: normal-mode &optional FIND-FILE
  325.      This function establishes the proper major mode and local variable
  326.      bindings for the current buffer.  First it calls `set-auto-mode',
  327.      then it runs `hack-local-variables' to parse, and bind or evaluate
  328.      as appropriate, any local variables.
  329.  
  330.      If the FIND-FILE argument to `normal-mode' is non-`nil',
  331.      `normal-mode' assumes that the `find-file' function is calling it.
  332.      In this case, it may process a local variables list at the end of
  333.      the file.  The variable `enable-local-variables' controls whether
  334.      to do so.
  335.  
  336.      If you run `normal-mode' yourself, the argument FIND-FILE is
  337.      normally `nil'.  In this case, `normal-mode' unconditionally
  338.      processes any local variables list.  *Note Local Variables in
  339.      Files: (emacs)File variables, for the syntax of the local
  340.      variables section of a file.
  341.  
  342.      `normal-mode' uses `condition-case' around the call to the major
  343.      mode function, so errors are caught and reported as a `File mode
  344.      specification error',  followed by the original error message.
  345.  
  346.  - User Option: enable-local-variables
  347.      This variable controls processing of local variables lists in files
  348.      being visited.  A value of `t' means process the local variables
  349.      lists unconditionally; `nil' means ignore them; anything else means
  350.      ask the user what to do for each file.  The default value is `t'.
  351.  
  352.  - User Option: enable-local-eval
  353.      This variable controls processing of `Eval:' in local variables
  354.      lists in files being visited.  A value of `t' means process them
  355.      unconditionally; `nil' means ignore them; anything else means ask
  356.      the user what to do for each file.  The default value is `maybe'.
  357.  
  358.  - Function: set-auto-mode
  359.      This function selects the major mode that is appropriate for the
  360.      current buffer.  It may base its decision on the value of the `-*-'
  361.      line, on the visited file name (using `auto-mode-alist'), or on the
  362.      value of a local variable).  However, this function does not look
  363.      for the `mode:' local variable near the end of a file; the
  364.      `hack-local-variables' function does that.  *Note How Major Modes
  365.      are Chosen: (emacs)Choosing Modes.
  366.  
  367.  - User Option: default-major-mode
  368.      This variable holds the default major mode for new buffers.  The
  369.      standard value is `fundamental-mode'.
  370.  
  371.      If the value of `default-major-mode' is `nil', Emacs uses the
  372.      (previously) current buffer's major mode for the major mode of a
  373.      new buffer.  However, if the major mode symbol has a `mode-class'
  374.      property with value `special', then it is not used for new buffers;
  375.      Fundamental mode is used instead.  The modes that have this
  376.      property are those such as Dired and Rmail that are useful only
  377.      with text that has been specially prepared.
  378.  
  379.  - Variable: initial-major-mode
  380.      The value of this variable determines the major mode of the initial
  381.      `*scratch*' buffer.  The value should be a symbol that is a major
  382.      mode command name.  The default value is `lisp-interaction-mode'.
  383.  
  384.  - Variable: auto-mode-alist
  385.      This variable contains an association list of file name patterns
  386.      (regular expressions; *note Regular Expressions::.) and
  387.      corresponding major mode functions.  Usually, the file name
  388.      patterns test for suffixes, such as `.el' and `.c', but this need
  389.      not be the case.  Each element of the alist looks like `(REGEXP .
  390.      mODE-FUNCTION)'.
  391.  
  392.      For example,
  393.  
  394.           (("^/tmp/fol/" . text-mode)
  395.            ("\\.texinfo$" . texinfo-mode)
  396.            ("\\.texi$" . texinfo-mode)
  397.  
  398.           ("\\.el$" . emacs-lisp-mode)
  399.            ("\\.c$" . c-mode)
  400.            ("\\.h$" . c-mode)
  401.            ...)
  402.  
  403.      When you visit a file whose *expanded* file name (*note File Name
  404.      Expansion::.) matches a REGEXP, `set-auto-mode' calls the
  405.      corresponding MODE-FUNCTION.  This feature enables Emacs to select
  406.      the proper major mode for most files.
  407.  
  408.      Here is an example of how to prepend several pattern pairs to
  409.      `auto-mode-alist'.  (You might use this sort of expression in your
  410.      `.emacs' file.)
  411.  
  412.           (setq auto-mode-alist
  413.             (append
  414.              ;; Filename starts with a dot.
  415.              '(("/\\.[^/]*$" . fundamental-mode)
  416.                ;; Filename has no dot.
  417.                ("[^\\./]*$" . fundamental-mode)
  418.                ("\\.C$" . c++-mode))
  419.              auto-mode-alist))
  420.  
  421.  - Function: hack-local-variables &optional FORCE
  422.      This function parses, and binds or evaluates as appropriate, any
  423.      local variables for the current buffer.
  424.  
  425.      The handling of `enable-local-variables' documented for
  426.      `normal-mode' actually takes place here.  The argument FORCE
  427.      reflects the argument FIND-FILE given to `normal-mode'.
  428.  
  429. 
  430. File: elisp,  Node: Mode Help,  Prev: Auto Major Mode,  Up: Major Modes
  431.  
  432. Getting Help about a Major Mode
  433. -------------------------------
  434.  
  435.    The `describe-mode' function is used to provide information about
  436. major modes.  It is normally called with `C-h m'.  The `describe-mode'
  437. function uses the value of `major-mode', which is why every major mode
  438. function needs to set the `major-mode' variable.
  439.  
  440.  - Command: describe-mode
  441.      This function displays the documentation of the current major mode.
  442.  
  443.      The `describe-mode' function calls the `documentation' function
  444.      using the value of `major-mode' as an argument.  Thus, it displays
  445.      the documentation string of the major mode function.  (*Note
  446.      Accessing Documentation::.)
  447.  
  448.  - Variable: major-mode
  449.      This variable holds the symbol for the current buffer's major
  450.      mode.  This symbol should be the name of the function that is
  451.      called to initialize the mode.  The `describe-mode' function uses
  452.      the documentation string of this symbol as the documentation of
  453.      the major mode.
  454.  
  455. 
  456. File: elisp,  Node: Minor Modes,  Next: Mode Line Format,  Prev: Major Modes,  Up: Modes
  457.  
  458. Minor Modes
  459. ===========
  460.  
  461.    A "minor mode" provides features that users may enable or disable
  462. independently of the choice of major mode.  Minor modes can be enabled
  463. individually or in combination.  Minor modes would be better named
  464. "Generally available, optional feature modes" except that such a name is
  465. unwieldy.
  466.  
  467.    A minor mode is not usually a modification of single major mode.  For
  468. example, Auto Fill mode may be used in any major mode that permits text
  469. insertion.  To be general, a minor mode must be effectively independent
  470. of the things major modes do.
  471.  
  472.    A minor mode is often much more difficult to implement than a major
  473. mode.  One reason is that you should be able to deactivate a minor mode
  474. and restore the environment of the major mode to the state it was in
  475. before the minor mode was activated.
  476.  
  477.    Often the biggest problem in implementing a minor mode is finding a
  478. way to insert the necessary hook into the rest of Emacs.  Minor mode
  479. keymaps make this easier.
  480.  
  481. * Menu:
  482.  
  483. * Minor Mode Conventions::      Tips for writing a minor mode.
  484. * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
  485.  
  486. 
  487. File: elisp,  Node: Minor Mode Conventions,  Next: Keymaps and Minor Modes,  Up: Minor Modes
  488.  
  489. Conventions for Writing Minor Modes
  490. -----------------------------------
  491.  
  492.    There are conventions for writing minor modes just as there are for
  493. major modes.  Several of the major mode conventions apply to minor
  494. modes as well: those regarding the name of the mode initialization
  495. function, the names of global symbols, and the use of keymaps and other
  496. tables.
  497.  
  498.    In addition, there are several conventions that are specific to
  499. minor modes.
  500.  
  501.    * Make a variable whose name ends in `-mode' to represent the minor
  502.      mode.  Its value should enable or disable the mode (`nil' to
  503.      disable; anything else to enable.)  We call this the "mode
  504.      variable".
  505.  
  506.      This variable is used in conjunction with the `minor-mode-alist' to
  507.      display the minor mode name in the mode line.  It can also enable
  508.      or disable a minor mode keymap.  Individual commands or hooks can
  509.      also check the variable's value.
  510.  
  511.      If you want the minor mode to be enabled separately in each buffer,
  512.      make the variable buffer-local.
  513.  
  514.    * Define a command whose name is the same as the mode variable.  Its
  515.      job is to enable and disable the mode by setting the variable.
  516.  
  517.      The command should accept one optional argument.  If the argument
  518.      is `nil', it should toggle the mode (turn it on if it is off, and
  519.      off if it is on).  Otherwise, it should turn the mode on if the
  520.      argument is a positive integer, a symbol other than `nil' or `-',
  521.      or a list whose CAR is such an integer or symbol; it should turn
  522.      the mode off otherwise.
  523.  
  524.      Here is an example taken from the definition of `overwrite-mode'.
  525.      It shows the use of `overwrite-mode' as a variable which enables or
  526.      disables the mode's behavior.
  527.  
  528.           (setq overwrite-mode
  529.                 (if (null arg) (not overwrite-mode)
  530.                   (> (prefix-numeric-value arg) 0)))
  531.  
  532.    * Add an element to `minor-mode-alist' for each minor mode (*note
  533.      Mode Line Variables::.).  This element should be a list of the
  534.      following form:
  535.  
  536.           (MODE-VARIABLE STRING)
  537.  
  538.      Here MODE-VARIABLE is the variable that controls enablement of the
  539.      minor mode, and STRING is a short string, starting with a space,
  540.      to represent the mode in the mode line.  These strings must be
  541.      short so that there is room for several of them at once.
  542.  
  543.      When you add an element to `minor-mode-alist', use `assq' to check
  544.      for an existing element, to avoid duplication.  For example:
  545.  
  546.           (or (assq 'leif-mode minor-mode-alist)
  547.               (setq minor-mode-alist
  548.                     (cons '(leif-mode " Leif") minor-mode-alist)))
  549.  
  550. 
  551. File: elisp,  Node: Keymaps and Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes
  552.  
  553. Keymaps and Minor Modes
  554. -----------------------
  555.  
  556.    As of Emacs version 19, each minor mode can have its own keymap
  557. which is active when the mode is enabled.  *Note Active Keymaps::.  To
  558. set up a keymap for a minor mode, add an element to the alist
  559. `minor-mode-map-alist'.
  560.  
  561.    One use of minor mode keymaps is to modify the behavior of certain
  562. self-inserting characters so that they do something else as well as
  563. self-insert.  This is the only way to accomplish this in general, since
  564. there is no way to customize what `self-insert-command' does except in
  565. certain special cases (designed for abbrevs and Auto Fill mode).  (Do
  566. not try substituting your own definition of `self-insert-command' for
  567. the standard one.  The editor command loop handles this function
  568. specially.)
  569.  
  570.  - Variable: minor-mode-map-alist
  571.      This variable is an alist of elements element that look like this:
  572.  
  573.           (VARIABLE . KEYMAP)
  574.  
  575.      where VARIABLE is the variable which indicates whether the minor
  576.      mode is enabled, and KEYMAP is the keymap.  The keymap KEYMAP is
  577.      active whenever VARIABLE has a non-`nil' value.
  578.  
  579.      Note that elements of `minor-mode-map-alist' do not have the same
  580.      structure as elements of `minor-mode-alist'.  The map must be the
  581.      CDR of the element; a list with the map as the second element will
  582.      not do.
  583.  
  584.      What's more, the keymap itself must appear in the CDR.  It does not
  585.      work to store a variable in the CDR and make the map the value of
  586.      that variable.
  587.  
  588.      When more than one minor mode keymap is active, their order of
  589.      priority is the order of `minor-mode-map-alist'.  But you should
  590.      design minor modes so that they don't interfere with each other.
  591.      If you do this properly, the order will not matter.
  592.  
  593. 
  594. File: elisp,  Node: Mode Line Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes
  595.  
  596. Mode Line Format
  597. ================
  598.  
  599.    Each Emacs window (aside from minibuffer windows) includes a mode
  600. line which displays status information about the buffer displayed in the
  601. window.  The mode line contains information about the buffer such as its
  602. name, associated file, depth of recursive editing, and the major and
  603. minor modes of the buffer.
  604.  
  605.    This section describes how the contents of the mode line are
  606. controlled.  It is in the chapter on modes because much of the
  607. information displayed in the mode line relates to the enabled major and
  608. minor modes.
  609.  
  610.    `mode-line-format' is a buffer-local variable that holds a template
  611. used to display the mode line of the current buffer.  All windows for
  612. the same buffer use the same `mode-line-format' and the mode lines will
  613. appear the same (except perhaps for the percentage of the file scrolled
  614. off the top).
  615.  
  616.    The mode line of a window is normally updated whenever a different
  617. buffer is shown in the window, or when the buffer's modified-status
  618. changes from `nil' to `t' or vice-versa.  If you modify any of the
  619. variables referenced by `mode-line-format', you may want to force an
  620. update of the mode line so as to display the new information.
  621.  
  622.  - Function: force-mode-line-update
  623.      Force redisplay of the current buffer's mode line.
  624.  
  625.    The mode line is usually displayed in inverse video; see
  626. `mode-line-inverse-video' in *Note Inverse Video::.
  627.  
  628. * Menu:
  629.  
  630. * Mode Line Data::        The data structure that controls the mode line.
  631. * Mode Line Variables::   Variables used in that data structure.
  632. * %-Constructs::          Putting information into a mode line.
  633.  
  634. 
  635. File: elisp,  Node: Mode Line Data,  Next: Mode Line Variables,  Prev: Mode Line Format,  Up: Mode Line Format
  636.  
  637. The Data Structure of the Mode Line
  638. -----------------------------------
  639.  
  640.    The mode line contents are controlled by a data structure of lists,
  641. strings, symbols and numbers kept in the buffer-local variable
  642. `mode-line-format'.  The data structure is called a "mode line
  643. construct", and it is built in recursive fashion out of simpler mode
  644. line constructs.
  645.  
  646.  - Variable: mode-line-format
  647.      The value of this variable is a mode line construct with overall
  648.      responsibility for the mode line format.  The value of this
  649.      variable controls which other variables are used to form the mode
  650.      line text, and where they appear.
  651.  
  652.    A mode line construct may be as simple as a fixed string of text, but
  653. it usually specifies how to use other variables to construct the text.
  654. Many of these variables are themselves defined to have mode line
  655. constructs as their values.
  656.  
  657.    The default value of `mode-line-format' incorporates the values of
  658. variables such as `mode-name' and `minor-mode-alist'.  Because of this,
  659. very few modes need to alter `mode-line-format'.  For most purposes, it
  660. is sufficient to alter the variables referenced by `mode-line-format'.
  661.  
  662.    A mode line construct may be a list, cons cell, symbol, or string.
  663. If the value is a list, each element may be a list, a cons cell, a
  664. symbol, or a string.
  665.  
  666. `STRING'
  667.      A string as a mode line construct is displayed verbatim in the
  668.      mode line except for "`%'-constructs".  Decimal digits after the
  669.      `%' specify the field width for space filling on the right (i.e.,
  670.      the data is left justified).  *Note %-Constructs::.
  671.  
  672. `SYMBOL'
  673.      A symbol as a mode line construct stands for its value.  The value
  674.      of SYMBOL is used in place of SYMBOL unless SYMBOL is `t' or
  675.      `nil', or is void, in which case SYMBOL is ignored.
  676.  
  677.      There is one exception: if the value of SYMBOL is a string, it is
  678.      processed verbatim in that the `%'-constructs are not recognized.
  679.  
  680. `(STRING REST...) or (LIST REST...)'
  681.      A list whose first element is a string or list, means to
  682.      concatenate all the elements.  This is the most common form of
  683.      mode line construct.
  684.  
  685. `(SYMBOL THEN ELSE)'
  686.      A list whose first element is a symbol is a conditional.  Its
  687.      meaning depends on the value of SYMBOL.  If the value is non-`nil',
  688.      the second element of the list (THEN) is processed recursively as
  689.      a mode line element.  But if the value of SYMBOL is `nil', the
  690.      third element of the list (if there is one) is processed
  691.      recursively.
  692.  
  693. `(WIDTH REST...)'
  694.      A list whose first element is an integer specifies truncation or
  695.      padding of the results of REST.  The remaining elements REST are
  696.      processed recursively as mode line constructs and concatenated
  697.      together.  Then the result is space filled (if WIDTH is positive)
  698.      or truncated (to -WIDTH columns, if WIDTH is negative) on the
  699.      right.
  700.  
  701.      For example, the usual way to show what percentage of a buffer is
  702.      above the top of the window is to use a list like this: `(-3 .
  703.      "%p")'.
  704.  
  705.    If you do alter `mode-line-format' itself, the new value should use
  706. all the same variables that are used by the default value, rather than
  707. duplicating their contents or displaying the information in another
  708. fashion.  This permits customizations made by the user, by libraries
  709. (such as `display-time') or by major modes via changes to those
  710. variables remain effective.
  711.  
  712.    Here is an example of a `mode-line-format' that might be useful for
  713. `shell-mode' since it contains the hostname and default directory.
  714.  
  715.      (setq mode-line-format
  716.        (list ""
  717.         'mode-line-modified
  718.         "%b--"
  719.         (getenv "HOST")      ; One element is not constant.
  720.         ":"
  721.         'default-directory
  722.         "   "
  723.         'global-mode-string
  724.         "   %[(" 'mode-name
  725.         'minor-mode-alist
  726.         "%n"
  727.         'mode-line-process
  728.         ")%]----"
  729.         '(-3 . "%p")
  730.         "-%-"))
  731.  
  732. 
  733. File: elisp,  Node: Mode Line Variables,  Next: %-Constructs,  Prev: Mode Line Data,  Up: Mode Line Format
  734.  
  735. Variables Used in the Mode Line
  736. -------------------------------
  737.  
  738.    This section describes variables incorporated by the standard value
  739. of `mode-line-format' into the text of the mode line.  There is nothing
  740. inherently special about these variables; any other variables could
  741. have the same effects on the mode line if `mode-line-format' were
  742. changed to use them.
  743.  
  744.  - Variable: mode-line-modified
  745.      This variable holds the value of the mode-line construct that
  746.      displays whether the current buffer is modified.
  747.  
  748.      The default value of `mode-line-modified' is `("--%1*%1*-")'.
  749.      This means that the mode line displays `--**-' if the buffer is
  750.      modified, `-----' if the buffer is not modified, and `--%%-' if
  751.      the buffer is read only.
  752.  
  753.      Changing this variable does not force an update of the mode line.
  754.  
  755.  - Variable: mode-line-buffer-identification
  756.      This variable identifies the buffer being displayed in the window.
  757.      Its default value is `Emacs: %17b', which means that it displays
  758.      `Emacs:' followed by the buffer name.  You may want to change this
  759.      in modes such as Rmail that do not behave like a "normal" Emacs.
  760.  
  761.  - Variable: global-mode-string
  762.      This variable holds a string that is displayed in the mode line.
  763.      The command `display-time' puts the time and load in this variable.
  764.      The `%M' construct substitutes the value of `global-mode-string',
  765.      but this is obsolete, since the variable is included directly in
  766.      the mode line.
  767.  
  768.  - Variable: mode-name
  769.      This buffer-local variable holds the "pretty" name of the current
  770.      buffer's major mode.  Each major mode should set this variable so
  771.      that the mode name will appear in the mode line.
  772.  
  773.  - Variable: minor-mode-alist
  774.      This variable holds an association list whose elements specify how
  775.      the mode line should indicate that a minor mode is active.  Each
  776.      element of the `minor-mode-alist' should be a two-element list:
  777.  
  778.           (MINOR-MODE-VARIABLE MODE-LINE-STRING)
  779.  
  780.      The string MODE-LINE-STRING is included in the mode line when the
  781.      value of MINOR-MODE-VARIABLE is non-`nil' and not otherwise.
  782.      These strings should begin with spaces so that they don't run
  783.      together.  Conventionally, the MINOR-MODE-VARIABLE for a specific
  784.      mode is set to a non-`nil' value when that minor mode is activated.
  785.  
  786.      The default value of `minor-mode-alist' is:
  787.  
  788.           minor-mode-alist
  789.           => ((abbrev-mode " Abbrev")
  790.               (overwrite-mode " Ovwrt")
  791.               (auto-fill-function " Fill")
  792.               (defining-kbd-macro " Def"))
  793.  
  794.      (In earlier Emacs versions, `auto-fill-function' was called
  795.      `auto-fill-hook'.)
  796.  
  797.      `minor-mode-alist' is not buffer-local.  The variables mentioned
  798.      in the alist should be buffer-local if the minor mode can be
  799.      enabled separately in each buffer.
  800.  
  801.  - Variable: mode-line-process
  802.      This buffer-local variable contains the mode line information on
  803.      process status in modes used for communicating with subprocesses.
  804.      It is displayed immediately following the major mode name, with no
  805.      intervening space.  For example, its value in the `*shell*' buffer
  806.      is `(": %s")', which allows the shell to display its status along
  807.      with the major mode as: `(Shell: run)'.  Normally this variable is
  808.      `nil'.
  809.  
  810.  - Variable: default-mode-line-format
  811.      This variable holds the default `mode-line-format' for buffers
  812.      that do not override it.  This is the same as `(default-value
  813.      'mode-line-format)'.
  814.  
  815.      The default value of `default-mode-line-format' is:
  816.  
  817.           (""
  818.            mode-line-modified
  819.            mode-line-buffer-identification
  820.            "   "
  821.            global-mode-string
  822.            "   %[("
  823.            mode-name
  824.            minor-mode-alist
  825.            "%n"
  826.            mode-line-process
  827.            ")%]----"
  828.            (-3 . "%p")
  829.            "-%-")
  830.  
  831. 
  832. File: elisp,  Node: %-Constructs,  Prev: Mode Line Variables,  Up: Mode Line Format
  833.  
  834. `%'-Constructs in the Mode Line
  835. -------------------------------
  836.  
  837.    The following table lists the recognized `%'-constructs and what
  838. they mean.
  839.  
  840. `%b'
  841.      the current buffer name, using the `buffer-name' function.
  842.  
  843. `%f'
  844.      the visited file name, using the `buffer-file-name' function.
  845.  
  846. `%*'
  847.      `%' if the buffer is read only (see `buffer-read-only');
  848.      `*' if the buffer is modified (see `buffer-modified-p');
  849.      `-' otherwise.
  850.  
  851. `%s'
  852.      the status of the subprocess belonging to the current buffer, using
  853.      `process-status'.
  854.  
  855. `%p'
  856.      the percent of the buffer above the top of window, or `Top',
  857.      `Bottom' or `All'.
  858.  
  859. `%n'
  860.      `Narrow' when narrowing is in effect; nothing otherwise (see
  861.      `narrow-to-region' in *Note Narrowing::).
  862.  
  863. `%['
  864.      an indication of the depth of recursive editing levels (not
  865.      counting minibuffer levels): one `[' for each editing level.
  866.  
  867. `%]'
  868.      one `]' for each recursive editing level (not counting minibuffer
  869.      levels).
  870.  
  871. `%%'
  872.      the character `%'--this is how to include a literal `%' in a
  873.      string in which `%'-constructs are allowed.
  874.  
  875. `%-'
  876.      dashes sufficient to fill the remainder of the mode line.
  877.  
  878.    The following two `%'-constructs are still supported but are
  879. obsolete since use of the `mode-name' and `global-mode-string'
  880. variables will produce the same results.
  881.  
  882. `%m'
  883.      the value of `mode-name'.
  884.  
  885. `%M'
  886.      the value of `global-mode-string'.  Currently, only `display-time'
  887.      modifies the value of `global-mode-string'.
  888.  
  889. 
  890. File: elisp,  Node: Hooks,  Prev: Mode Line Format,  Up: Modes
  891.  
  892. Hooks
  893. =====
  894.  
  895.    A "hook" is a variable where you can store a function or functions
  896. to be called on a particular occasion by an existing program.  Emacs
  897. provides lots of hooks for the sake of customization.  Most often, hooks
  898. are set up in the `.emacs' file, but Lisp programs can set them also.
  899. *Note Standard Hooks::, for a list of standard hook variables.
  900.  
  901.    Most of the hooks in Emacs are "normal hooks".  These variables
  902. contain lists of functions to be called with no arguments.  The reason
  903. most hooks are normal hooks is so that you can use them in a uniform
  904. way.  You can always tell when a hook is a normal hook, because its
  905. name ends in `-hook'.
  906.  
  907.    The recommended way to add a hook function to a normal hook is by
  908. calling `add-hook' (see below).  The hook functions may be any of the
  909. valid kinds of functions that `funcall' accepts (*note What Is a
  910. Function::.).  Most normal hook variables are initially void;
  911. `add-hook' knows how to deal with this.
  912.  
  913.    As for abnormal hooks, those whose names end in `-function' have a
  914. value which is a single function.  Those whose names end in `-hooks'
  915. have a value which is a list of functions.  Any hook which is abnormal
  916. is abnormal because a normal hook won't do the job; either the
  917. functions are called with arguments, or their values are meaningful.
  918. The name shows you that the hook is abnormal and you need to look up
  919. how to use it properly.
  920.  
  921.    Most major modes run hooks as the last step of initialization.  This
  922. makes it easy for a user to customize the behavior of the mode, by
  923. overriding the local variable assignments already made by the mode.  But
  924. hooks may also be used in other contexts.  For example, the hook
  925. `suspend-hook' runs just before Emacs suspends itself (*note Suspending
  926. Emacs::.).
  927.  
  928.    For example, you can put the following expression in your `.emacs'
  929. file if you want to turn on Auto Fill mode when in Lisp Interaction
  930. mode:
  931.  
  932.      (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
  933.  
  934.    The next example shows how to use a hook to customize the way Emacs
  935. formats C code.  (People often have strong personal preferences for one
  936. format compared to another.)  Here the hook function is an anonymous
  937. lambda expression.
  938.  
  939.      (add-hook 'c-mode-hook
  940.        (function (lambda ()
  941.                    (setq c-indent-level 4
  942.                          c-argdecl-indent 0
  943.                          c-label-offset -4
  944.                          c-continued-statement-indent 0
  945.                          c-brace-offset 0
  946.                          comment-column 40))))
  947.      
  948.      (setq c++-mode-hook c-mode-hook)
  949.  
  950.    Finally, here is an example of how to use the Text mode hook to
  951. provide a customized mode line for buffers in Text mode, displaying the
  952. default directory in addition to the standard components of the mode
  953. line.  (This may cause the mode line to run out of space if you have
  954. very long file names or display the time and load.)
  955.  
  956.      (add-hook 'text-mode-hook
  957.        (function (lambda ()
  958.                    (setq mode-line-format
  959.                          '(mode-line-modified
  960.                            "Emacs: %14b"
  961.                            "  "
  962.                            default-directory
  963.                            " "
  964.                            global-mode-string
  965.                            "%[("
  966.                            mode-name
  967.                            minor-mode-alist
  968.                            "%n"
  969.                            mode-line-process
  970.                            ") %]---"
  971.                            (-3 . "%p")
  972.                            "-%-")))))
  973.  
  974.    At the appropriate time, Emacs uses the `run-hooks' function to run
  975. particular hooks.  This function calls the hook functions you have
  976. added with `add-hooks'.
  977.  
  978.  - Function: run-hooks &rest HOOKVAR
  979.      This function takes one or more hook names as arguments and runs
  980.      each one in turn.  Each HOOKVAR argument should be a symbol that
  981.      is a hook variable.  These arguments are processed in the order
  982.      specified.
  983.  
  984.      If a hook variable has a non-`nil' value, that value may be a
  985.      function or a list of functions.  If the value is a function
  986.      (either a lambda expression or a symbol with a function
  987.      definition), it is called.  If it is a list, the elements are
  988.      called, in order.  The hook functions are called with no arguments.
  989.  
  990.      For example:
  991.  
  992.           (run-hooks 'emacs-lisp-mode-hook)
  993.  
  994.      Major mode functions use this function to call any hooks defined
  995.      by the user.
  996.  
  997.  - Function: add-hook HOOK FUNCTION &optional APPEND
  998.      This function is the handy way to add function FUNCTION to hook
  999.      variable HOOK.  For example,
  1000.  
  1001.           (add-hook 'text-mode-hook 'my-text-hook-function)
  1002.  
  1003.      adds `my-text-hook-function' to the hook called `text-mode-hook'.
  1004.  
  1005.      It is best to design your hook functions so that the order in
  1006.      which they are executed does not matter.  Any dependence on the
  1007.      order is "asking for trouble."  However, the order is predictable:
  1008.      normally, FUNCTION goes at the front of the hook list, so it will
  1009.      be executed first (barring another `add-hook' call).
  1010.  
  1011.      If the optional argument APPEND is non-`nil', the new hook
  1012.      function goes at the end of the hook list and will be executed
  1013.      last.
  1014.  
  1015. 
  1016. File: elisp,  Node: Documentation,  Next: Files,  Prev: Modes,  Up: Top
  1017.  
  1018. Documentation
  1019. *************
  1020.  
  1021.    GNU Emacs Lisp has convenient on-line help facilities, most of which
  1022. derive their information from the documentation strings associated with
  1023. functions and variables.  This chapter describes how to write good
  1024. documentation strings for your Lisp programs, as well as how to write
  1025. programs to access documentation.
  1026.  
  1027.    Note that the documentation strings for Emacs are not the same thing
  1028. as the Emacs manual.  Manuals have their own source files, written in
  1029. the Texinfo language; documentation strings are specified in the
  1030. definitions of the functions and variables they apply to.  A collection
  1031. of documentation strings is not sufficient as a manual because a good
  1032. manual is not organized in that fashion; it is organized in terms of
  1033. topics of discussion.
  1034.  
  1035. * Menu:
  1036.  
  1037. * Documentation Basics::      Good style for doc strings.
  1038.                                 Where to put them.  How Emacs stores them.
  1039. * Accessing Documentation::   How Lisp programs can access doc strings.
  1040. * Keys in Documentation::     Substituting current key bindings.
  1041. * Describing Characters::     Making printable descriptions of
  1042.                                 non-printing characters and key sequences.
  1043. * Help Functions::            Subroutines used by Emacs help facilities.
  1044.  
  1045. 
  1046. File: elisp,  Node: Documentation Basics,  Next: Accessing Documentation,  Prev: Documentation,  Up: Documentation
  1047.  
  1048. Documentation Basics
  1049. ====================
  1050.  
  1051.    A documentation string is written using the Lisp syntax for strings,
  1052. with double-quote characters surrounding the text of the string.  This
  1053. is because it really is a Lisp string object.  The string serves as
  1054. documentation when it is written in the proper place in the definition
  1055. of a function or variable.  In a function definition, the documentation
  1056. string follows the argument list.  In a variable definition, the
  1057. documentation string follows the initial value of the variable.
  1058.  
  1059.    When you write a documentation string, make the first line a complete
  1060. sentence (or two complete sentences) since some commands, such as
  1061. `apropos', print only the first line of a multi-line documentation
  1062. string.  Also, you should not indent the second line of a documentation
  1063. string, if you have one, because that looks odd when you use `C-h f'
  1064. (`describe-function') or `C-h v' (`describe-variable').
  1065.  
  1066.    Documentation strings may contain several special substrings, which
  1067. stand for key bindings to be looked up in the current keymaps when the
  1068. documentation is displayed.  This allows documentation strings to refer
  1069. to the keys for related commands and be accurate even when a user
  1070. rearranges the key bindings.  (*Note Accessing Documentation::.)
  1071.  
  1072.    Within the Lisp world, a documentation string is kept with the
  1073. function or variable that it describes:
  1074.  
  1075.    * The documentation for a function is stored in the function
  1076.      definition itself (*note Lambda Expressions::.).  The function
  1077.      `documentation' knows how to extract it.
  1078.  
  1079.    * The documentation for a variable is stored on the variable's
  1080.      property list under the property name `variable-documentation'.
  1081.      The function `documentation-property' knows how to extract it.
  1082.  
  1083.    However, to save space, the documentation for preloaded functions and
  1084. variables (including primitive functions and autoloaded functions) are
  1085. stored in the `emacs/etc/DOC-VERSION' file.  Both the `documentation'
  1086. and the `documentation-property' functions know how to access
  1087. `emacs/etc/DOC-VERSION', and the process is transparent to the user.
  1088. In this case, the documentation string is replaced with an integer
  1089. offset into the `emacs/etc/DOC-VERSION' file.  Keeping the documentation
  1090. strings out of the Emacs core image saves a significant amount of space.
  1091. *Note Building Emacs::.
  1092.  
  1093.    For information on the uses of documentation strings, see *Note
  1094. Help: (emacs)Help.
  1095.  
  1096.    The `emacs/etc' directory contains two utilities that you can use to
  1097. print nice-looking hardcopy for the file `emacs/etc/DOC-VERSION'.
  1098. These are `sorted-doc.c' and `digest-doc.c'.
  1099.  
  1100.