home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / info / elisp.i13 (.txt) < prev    next >
GNU Info File  |  1993-06-14  |  52KB  |  929 lines
  1. This is Info file elisp, produced by Makeinfo-1.47 from the input file
  2. elisp.texi.
  3.    This file documents GNU Emacs Lisp.
  4.    This is edition 1.03 of the GNU Emacs Lisp Reference Manual, for
  5. Emacs Version 18.
  6.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  7. Cambridge, MA 02139 USA
  8.    Copyright (C) 1990 Free Software Foundation, Inc.
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Foundation.
  20. File: elisp,  Node: Minor Modes,  Next: Mode Line Format,  Prev: Major Modes,  Up: Modes
  21. Minor Modes
  22. ===========
  23.    A "minor mode" provides features that users may enable or disable
  24. independently of the choice of major mode.  Minor modes can be enabled
  25. individually or in combination.  Minor modes would be better named
  26. "Generally available, optional feature modes" except that such a name is
  27. unwieldy.
  28.    A minor mode is not usually a modification of single major mode.  For
  29. example, `auto-fill-mode' and `auto-justify-mode' may be used in any
  30. major mode that permits text insertion.  To be general, a minor mode
  31. must be effectively independent of the things major modes do.
  32.    A minor mode is often much more difficult to implement than a major
  33. mode.  One reason is that you should be able to deactivate a minor mode
  34. and restore the environment of the major mode to the state it was in
  35. before the minor mode was activated.
  36.    Often the biggest problem in implementing a minor mode is finding a
  37. way to insert the necessary hook into the rest of Emacs.  For example,
  38. some minor modes, such as Auto Fill mode, change how text is inserted
  39. into a buffer.  Without `auto-fill-hook', Auto Fill mode would be
  40. implementable only at great pain and great cost in editing efficiency.
  41. * Menu:
  42. * Minor Mode Conventions::      Tips for writing a minor mode.
  43. * Limits of Minor Modes::       Minor modes are of limited generality.
  44. File: elisp,  Node: Minor Mode Conventions,  Next: Limits of Minor Modes,  Prev: Minor Modes,  Up: Minor Modes
  45. Conventions for Writing Minor Modes
  46. -----------------------------------
  47.    There are conventions for writing minor modes just as there are for
  48. major modes.  Several of the major mode conventions apply to minor
  49. modes as well: those regarding the name of the mode initialization
  50. function, the names of global symbols, and the use of keymaps and other
  51. tables.
  52.    In addition, there are several conventions that are specific to
  53. minor modes.
  54.    * The minor mode should be represented by a symbol whose name ends in
  55.      `-mode'.  This symbol should be both a command to turn the mode on
  56.      or off and a variable which records whether the mode is on.
  57.      This variable is used in conjunction with the `minor-mode-alist' to
  58.      display the minor mode name in the mode line.  It may also be
  59.      directly responsible for controlling the features of the minor
  60.      mode.
  61.      If you want the minor mode to be enabled separately in each buffer,
  62.      make the variable buffer-local.
  63.    * A minor mode command should accept one optional argument.  If the
  64.      argument is `nil', the function should toggle the mode (turn it on
  65.      if it is off, and off if it is on).  Otherwise, the function
  66.      should turn the mode on if the argument is a positive integer, a
  67.      symbol, or a list whose CAR is a positive integer; it should turn
  68.      the mode off otherwise.  (This convention has not been implemented
  69.      with full consistency in Emacs version 18.)
  70.      Here is an example taken from the definition of `overwrite-mode':
  71.           (setq overwrite-mode
  72.                 (if (null arg) (not overwrite-mode)
  73.                   (> (prefix-numeric-value arg) 0)))
  74.    * Add an element to `minor-mode-alist' for each minor mode (*note
  75.      Mode Line Variables::.).  This element should be a list of the
  76.      following form:
  77.           (MODE-VARIABLE STRING)
  78.      Here MODE-VARIABLE is the variable that indicates the enablement
  79.      of the minor mode, and STRING is a short string, starting with a
  80.      space, to represent the mode in the mode line.  These strings must
  81.      be short so that there is room for several of them at once.
  82.      When you add an element to `minor-mode-alist', use `assq' to check
  83.      for an existing element, to avoid duplication.  For example:
  84.           (or (assq 'leif-mode minor-mode-alist)
  85.               (setq minor-mode-alist
  86.                     (cons '(leif-mode " Leif") minor-mode-alist)))
  87.    * If the minor mode adds new key bindings to the local keymap, you
  88.      should be able to restore the keymap to its original value when you
  89.      deactivate the minor mode.
  90. File: elisp,  Node: Limits of Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes
  91. Limitations of Minor Modes
  92. --------------------------
  93.    It is very difficult to write a minor mode that responds to arbitrary
  94. self-inserting characters.  The principal problem is that
  95. `self-insert-command', the command to insert the last key typed, is a
  96. primitive function written in C.  It does not call any hooks, except in
  97. special cases.
  98.    Unfortunately, you cannot simply substitute your own definition of
  99. `self-insert-command' for the existing one, as you can with most
  100. functions.  This is a consequence of the way the editor command loop
  101. works: it checks whether a key is bound to `self-insert-command' and,
  102. if so, it calls the primitive `self-insert-command' function directly. 
  103. It does not check to see whether you have written another version of
  104. the function to substitute for it.  This is done for speed. (In
  105. general, if you substitute a Lisp function for a primitive, the C code
  106. within Emacs will continue to call the original primitive, but Lisp
  107. code will call your substitute Lisp function.)
  108.    Instead of attempting to replace the function definition for
  109. `self-insert-command', you could rebind certain keys that call
  110. `self-insert-command'.  This can be made to work as long as no two
  111. minor modes try to rebind the same key.  In a minor mode that is global
  112. (affects all buffers), do the rebinding in the global map.  In a minor
  113. mode that is local to individual buffers, you will need to copy the
  114. local keymap (since it is usually shared with all the other buffers in
  115. the same major mode) and then make the change.
  116. File: elisp,  Node: Mode Line Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes
  117. Mode Line Format
  118. ================
  119.    Each Emacs window includes a mode line which displays status
  120. information about the buffer displayed in the window.  The mode line
  121. contains information about the buffer such as its name, associated file,
  122. depth of recursive editing, and the major and minor modes of the buffer.
  123. This section describes how the contents of the mode line are controlled.
  124. It is in the chapter on modes because much of the information displayed
  125. in the mode line relates to the enabled major and minor modes.
  126.    `mode-line-format' is a buffer-local variable that holds a template
  127. used to display the mode line of the current buffer.  All windows for
  128. the same buffer use the same `mode-line-format' and the mode lines will
  129. appear the same (except perhaps for the percentage of the file scrolled
  130. off the top).
  131.    The mode line of a window is normally updated whenever a different
  132. buffer is shown in the window, or when the buffer's modified-status
  133. changes from `nil' to `t' or vice-versa.  If you modify any of the
  134. variables referenced by `mode-line-format', you may want to force an
  135. update of the mode line so as to display the new information. You can
  136. do this with the following expression:
  137.      (set-buffer-modified-p (buffer-modified-p))
  138.    The mode line is usually displayed in inverse video; see
  139. `mode-line-inverse-video' in *Note Screen Attributes::.
  140. * Menu:
  141. * Mode Line Data::        The data structure that controls the mode line.
  142. * Mode Line Variables::   Variables used in that data structure.
  143. * %-Constructs::          Putting information into a mode line.
  144. File: elisp,  Node: Mode Line Data,  Next: Mode Line Variables,  Prev: Mode Line Format,  Up: Mode Line Format
  145. The Data Structure of the Mode Line
  146. -----------------------------------
  147.    The mode line contents are controlled by a data structure of lists,
  148. strings, symbols and numbers kept in the buffer-local variable
  149. `mode-line-format'.  The data structure is called a "mode line
  150. construct", and it is built in recursive fashion out of simpler mode
  151. line constructs.
  152.  -- Variable: mode-line-format
  153.      The value of this variable is a mode line construct with overall
  154.      responsibility for the mode line format.  The value of this
  155.      variable controls which other variables are used to form the mode
  156.      line text, and where they appear.
  157.    A mode line construct may be as simple as a fixed string of text, but
  158. it usually specifies how to use other variables to construct the text.
  159. Many of these variables are themselves defined to have mode line
  160. constructs as their values.
  161.    The default value of `mode-line-format' incorporates the values of
  162. variables such as `mode-name' and `minor-mode-alist'. Because of this,
  163. very few modes need to alter `mode-line-format'. For most purposes, it
  164. is sufficient to alter the variables referenced by `mode-line-format'.
  165.    A mode line construct may be a list, cons cell, symbol, or string. 
  166. If the value is a list, each element may be a list, a cons cell, a
  167. symbol, or a string.
  168. `STRING'
  169.      A string as a mode line construct is displayed verbatim in the
  170.      mode line except for "`%'-constructs".  Decimal digits after the
  171.      `%' specify the field width for space filling on the right (i.e.,
  172.      the data is left justified).  *Note %-Constructs::.
  173. `SYMBOL'
  174.      A symbol as a mode line construct stands for its value.  The value
  175.      of SYMBOL is used in place of SYMBOL unless SYMBOL is `t' or
  176.      `nil', or is void, in which case SYMBOL is ignored.
  177.      There is one exception: if the value of SYMBOL is a string, it is
  178.      processed verbatim in that the `%'-constructs are not recognized.
  179. `(STRING REST...) or (LIST REST...)'
  180.      A list whose first element is a string or list, means to
  181.      concatenate all the elements.  This is the most common form of
  182.      mode line construct.
  183. `(SYMBOL THEN ELSE)'
  184.      A list whose first element is a symbol is a conditional.  Its
  185.      meaning depends on the value of SYMBOL.  If the value is non-`nil',
  186.      the second element of the list (THEN) is processed recursively as
  187.      a mode line element.  But if the value of SYMBOL is `nil', the
  188.      third element of the list (if there is one) is processed
  189.      recursively.
  190. `(WIDTH REST...)'
  191.      A list whose first element is an integer specifies truncation or
  192.      padding of the results of REST.  The remaining elements REST are
  193.      processed recursively as mode line constructs and concatenated
  194.      together.  Then the result is space filled (if WIDTH is positive)
  195.      or truncated (to -WIDTH columns, if WIDTH is negative) on the
  196.      right.
  197.      For example, the usual way to show what percentage of a buffer is
  198.      above the top of the window is to use a list like this: `(-3 . 
  199.      "%p")'.
  200.    If you do alter `mode-line-format' itself, the new value should use
  201. all the same variables that are used by the default value, rather than
  202. duplicating their contents or displaying the information in another
  203. fashion.  This permits customizations made by the user, by libraries
  204. (such as `display-time') or by major modes via changes to those
  205. variables remain effective.
  206.    Here is an example of a `mode-line-format' that might be useful for
  207. `shell-mode' since it contains the hostname and default directory.
  208.      (setq mode-line-format
  209.        (list ""
  210.         'mode-line-modified
  211.         "%b--"
  212.         (getenv "HOST")      ; One element is not constant.
  213.         ":"
  214.         'default-directory
  215.         "   "
  216.         'global-mode-string
  217.         "   %[(" 'mode-name
  218.         'minor-mode-alist
  219.         "%n"
  220.         'mode-line-process
  221.         ")%]----"
  222.         '(-3 . "%p")
  223.         "-%-"))
  224. File: elisp,  Node: Mode Line Variables,  Next: %-Constructs,  Prev: Mode Line Data,  Up: Mode Line Format
  225. Variables Used in the Mode Line
  226. -------------------------------
  227.    This section describes variables incorporated by the standard value
  228. of `mode-line-format' into the text of the mode line.  There is nothing
  229. inherently special about these variables; any other variables could
  230. have the same effects on the mode line if `mode-line-format' were
  231. changed to use them.
  232.  -- Variable: mode-line-modified
  233.      This variable holds the mode-line construct for displaying whether
  234.      the current buffer is modified.
  235.      The default value `mode-line-modified' is `("--%1*%1*-")'. This
  236.      means that the mode line displays `--**-' if the buffer is
  237.      modified, `-----' if the buffer is not modified, and `--%%-' if
  238.      the buffer is read only.
  239.      Changing this variable does not force an update of the mode line.
  240.  -- Variable: mode-line-buffer-identification
  241.      This variable identifies the buffer being displayed in the window.
  242.      Its default value is `Emacs: %17b', which means that it displays
  243.      `Emacs:' followed by the buffer name.  You may want to change this
  244.      in modes such as Rmail that do not behave like a "normal" Emacs.
  245.  -- Variable: global-mode-string
  246.      This variable holds a string that is displayed in the mode line for
  247.      the use of `display-time'.  The `%M' construct substitutes the
  248.      value of `global-mode-string', but this is obsolete, since the
  249.      variable is included directly in the mode line.
  250.  -- Variable: mode-name
  251.      This buffer-local variable holds the "pretty" name of the current
  252.      buffer's major mode.  Each major mode should set this variable so
  253.      that the mode name will appear in the mode line.
  254.  -- Variable: minor-mode-alist
  255.      This variable holds an association list whose elements specify how
  256.      the mode line should indicate that a minor mode is active.  Each
  257.      element of the `minor-mode-alist' should be a two-element list:
  258.           (MINOR-MODE-VARIABLE MODE-LINE-STRING)
  259.      The string MODE-LINE-STRING is included in the mode line when the
  260.      value of MINOR-MODE-VARIABLE is non-`nil' and not otherwise. 
  261.      These strings should begin with spaces so that they don't run
  262.      together.  Conventionally, the MINOR-MODE-VARIABLE for a specific
  263.      mode is set to a non-`nil' value when that minor mode is activated.
  264.      The default value of `minor-mode-alist' is:
  265.           minor-mode-alist
  266.           => ((abbrev-mode " Abbrev")
  267.               (overwrite-mode " Ovwrt")
  268.               (auto-fill-hook " Fill")
  269.               (defining-kbd-macro " Def"))
  270.      (Note that in version 19, `auto-fill-hook' will be renamed to
  271.      `auto-fill-function'.)
  272.      `minor-mode-alist' is not buffer-local.  The variables mentioned
  273.      in the alist should be buffer-local if the minor mode can be
  274.      enabled separately in each buffer.
  275.  -- Variable: mode-line-process
  276.      This buffer-local variable contains the mode line information on
  277.      process status in modes used for communicating with subprocesses. 
  278.      It is displayed immediately following the major mode name, with no
  279.      intervening space.  For example, its value in the `*shell*' buffer
  280.      is `(": %s")', which allows the shell to display its status along
  281.      with the major mode as: `(Shell: run)'.  Normally this variable is
  282.      `nil'.
  283.  -- Variable: default-mode-line-format
  284.      This variable holds the default `mode-line-format' for buffers
  285.      that do not override it.  This is the same as `(default-value
  286.      'mode-line-format)'.
  287.      The default value of `default-mode-line-format' is:
  288.           (""
  289.            mode-line-modified
  290.            mode-line-buffer-identification
  291.            "   "
  292.            global-mode-string
  293.            "   %[("
  294.            mode-name
  295.            minor-mode-alist
  296.            "%n"
  297.            mode-line-process
  298.            ")%]----"
  299.            (-3 . "%p")
  300.            "-%-")
  301. File: elisp,  Node: %-Constructs,  Prev: Mode Line Variables,  Up: Mode Line Format
  302. `%'-Constructs in the Mode Line
  303. -------------------------------
  304.    The following table lists the recognized `%'-constructs and what
  305. they mean.
  306.      the current buffer name, using the `buffer-name' function.
  307.      the visited file name, using the `buffer-file-name' function.
  308.      `%' if the buffer is read only (see `buffer-read-only');
  309.      `*' if the buffer is modified (see `buffer-modified-p');
  310.      `-' otherwise.
  311.      the status of the subprocess belonging to the current buffer, using
  312.      `process-status'.
  313.      the percent of the buffer above the top of window, or `Top',
  314.      `Bottom' or `All'.
  315.      `Narrow' when narrowing is in effect; nothing otherwise (see
  316.      `narrow-to-region' in *Note Narrowing::).
  317.      an indication of the depth of recursive editing levels (not
  318.      counting minibuffer levels): one `[' for each editing level.
  319.      one `]' for each recursive editing level (not counting minibuffer
  320.      levels).
  321.      the character `%'--this is how to include a literal `%' in a
  322.      string in which `%'-constructs are allowed.
  323.      dashes sufficient to fill the remainder of the mode line.
  324.    The following two `%'-constructs are still supported but are
  325. obsolete since use of the `mode-name' and `global-mode-string'
  326. variables will produce the same results.
  327.      the value of `mode-name'.
  328.      the value of `global-mode-string'. Currently, only `display-time'
  329.      modifies `global-mode-string'.
  330. File: elisp,  Node: Hooks,  Prev: Mode Line Format,  Up: Modes
  331. Hooks
  332. =====
  333.    A "hook" is a variable whose value is a "hook function" (or a list
  334. of hook functions) to be called by parts of Emacs on certain defined
  335. occasions.  The purpose of hooks is to facilitate customization, and
  336. the value of a hook is most often set up in the `.emacs' file, but it
  337. may be changed by programs.  The function or functions used in a hook
  338. may be any of the valid kinds of functions that `funcall' accepts
  339. (*note What Is a Function::.).
  340.    Most modes run hooks as the last step of initialization.  This makes
  341. it easy for a user to customize the behavior of the mode, by overriding
  342. the local variable assignments already made by the mode.  But hooks may
  343. also be used in other contexts.  For example, the functions named by
  344. `find-file-not-found-hooks' are called whenever a file is not found by
  345. `find-file'.
  346.    For example, you can put the following expression in your `.emacs'
  347. file if you want to turn on Auto Fill mode when in Lisp Interaction
  348. mode:
  349.      (setq lisp-interaction-mode-hook 'turn-on-auto-fill)
  350.    The next example shows how to use a hook to customize the way Emacs
  351. formats C code.  (People often have strong personal preferences for one
  352. format compared to another.)  Here the hook function is an anonymous
  353. lambda expression.
  354.      (setq c-mode-hook
  355.            (function (lambda ()
  356.                        (setq c-indent-level 4
  357.                              c-argdecl-indent 0
  358.                              c-label-offset -4
  359.                              c-continued-statement-indent 0
  360.                              c-brace-offset 0
  361.                              comment-column 40))))
  362.      
  363.      (setq c++-mode-hook c-mode-hook)
  364.    Finally, here is an example of how to use the Text mode hook to
  365. provide a customized mode line for buffers in Text mode, displaying the
  366. default directory in addition to the standard components of the mode
  367. line.  (This may cause the mode line to run out of space if you have
  368. very long path names or display the time and load.)
  369.      (setq text-mode-hook
  370.            (function (lambda ()
  371.                        (setq mode-line-format
  372.                              '(mode-line-modified
  373.                                "Emacs: %14b"
  374.                                "  "
  375.                                default-directory
  376.                                " "
  377.                                global-mode-string
  378.                                "%[("
  379.                                mode-name
  380.                                minor-mode-alist
  381.                                "%n"
  382.                                mode-line-process
  383.                                ") %]---"
  384.                                (-3 . "%p")
  385.                                "-%-")))))
  386.    *Note Standard Hooks::, for a list of standard hook variables.
  387.    Most hook variables are initially void.  This has no effect on
  388. examples such as the previous ones, where the hook variable is set
  389. without reference to any previous value.  However, if you want to add an
  390. element to a hook variable which you use as a list of functions, you
  391. need to make sure the variable is not void.  Here is how to do it using
  392. `defvar':
  393.      (defvar foo-hook nil)
  394.      (or (memq 'my-hook foo-hook)
  395.          (setq foo-hook (cons 'my-hook foo-hook)))
  396.    At the appropriate time, Emacs uses the `run-hooks' function to run
  397. the hooks you have specified.
  398.  -- Function: run-hooks &rest HOOKVAR
  399.      This function takes one or more hook names as arguments and runs
  400.      each one in turn.  Each HOOKVAR argument should be a symbol that
  401.      is a hook variable.  These arguments are processed in the order
  402.      specified.
  403.      If a hook variable has a non-`nil' value, that value may be a
  404.      function or a list of functions.  If the value is a function
  405.      (either a lambda expression or a symbol with a function
  406.      definition), it is called.  If it is a list, the elements are
  407.      called, in order. The hook functions are called with no arguments.
  408.      For example:
  409.           (run-hooks 'emacs-lisp-mode-hook)
  410.      Major mode functions use this function to call any hooks defined
  411.      by the user.
  412. File: elisp,  Node: Documentation,  Next: Files,  Prev: Modes,  Up: Top
  413. Documentation
  414. *************
  415.    GNU Emacs Lisp has convenient on-line help facilities, most of which
  416. derive their information from the documentation strings associated with
  417. functions and variables.  This chapter describes how to write good
  418. documentation strings for your Lisp programs, as well as how to write
  419. programs to access documentation.
  420.    Note that the documentation strings for Emacs are not the same thing
  421. as the Emacs manual.  Manuals have their own source files, written in
  422. the Texinfo language; documentation strings are specified in the
  423. definitions of the functions and variables they apply to.  A collection
  424. of documentation strings is not sufficient as a manual because a good
  425. manual is not organized in that fashion; it is organized in terms of
  426. topics of discussion.
  427. * Menu:
  428. * Documentation Basics::      Good style for doc strings.
  429.                                 Where to put them.  How Emacs stores them.
  430. * Accessing Documentation::   How Lisp programs can access doc strings.
  431. * Keys in Documentation::     Substituting current key bindings.
  432. * Describing Characters::     Making printable descriptions of
  433.                                 non-printing characters and key sequences.
  434. * Help Functions::            Subroutines used by Emacs help facilities.
  435. File: elisp,  Node: Documentation Basics,  Next: Accessing Documentation,  Prev: Documentation,  Up: Documentation
  436. Documentation Basics
  437. ====================
  438.    A documentation string is written using the Lisp syntax for strings,
  439. with double-quote characters surrounding the text of the string.  This
  440. is because it really is a Lisp string object.  The string serves as
  441. documentation when it is written in the proper place in the definition
  442. of a function or variable.  In a function definition, the documentation
  443. string follows the argument list.  In a variable definition, the
  444. documentation string follows the initial value of the variable.
  445.    When you write a documentation string, make the first line a complete
  446. sentence (or two complete sentences) since some commands, such as
  447. `apropos', print only the first line of a multi-line documentation
  448. string.  Also, you should not indent the second line of a documentation
  449. string, if you have one, because that looks odd when you use `C-h f'
  450. (`describe-function') or `C-h v' (`describe-variable').
  451.    Documentation strings may contain several special substrings, which
  452. stand for key bindings to be looked up in the current keymaps when the
  453. documentation is displayed.  This allows documentation strings to refer
  454. to the keys for related commands and be accurate even when a user
  455. rearranges the key bindings.  (*Note Accessing Documentation::.)
  456.    Within the Lisp world, a documentation string is kept with the
  457. function or variable that it describes:
  458.    * The documentation for a function is stored in the function
  459.      definition itself (*note Lambda Expressions::.).  The function
  460.      `documentation' knows how to extract it.
  461.    * The documentation for a variable is stored on the variable's
  462.      property list under the property name `variable-documentation'. 
  463.      The function `documentation-property' knows how to extract it.
  464.    However, to save space, the documentation for preloaded functions and
  465. variables (including primitive functions and autoloaded functions) are
  466. stored in the `emacs/etc/DOC-VERSION' file.  Both the `documentation'
  467. and the `documentation-property' functions know how to access
  468. `emacs/etc/DOC-VERSION', and the process is transparent to the user. 
  469. In this case, the documentation string is replaced with an integer
  470. offset into the `emacs/etc/DOC-VERSION' file.  Keeping the documentation
  471. strings out of the Emacs core image saves a significant amount of space.
  472. *Note Building Emacs::.
  473.    For information on the uses of documentation strings, see
  474. `where-is-internal' and `describe-bindings' in *Note Global and Local
  475. Keymaps::.  Also, see *Note Help: (emacs)Help.
  476.    The `emacs/etc' directory contains two utilities for printing the
  477. `emacs/etc/DOC-VERSION' file in hardcopy.  These are `sorted-doc.c' and
  478. `digest-doc.c'.
  479. File: elisp,  Node: Accessing Documentation,  Next: Keys in Documentation,  Prev: Documentation Basics,  Up: Documentation
  480. Access to Documentation Strings
  481. ===============================
  482.  -- Function: documentation-property SYMBOL PROPERTY
  483.      This function returns the documentation string that is recorded
  484.      SYMBOL's property list under property PROPERTY.  This uses the
  485.      function `get', but does more than that: it also retrieves the
  486.      string from the file `emacs/etc/DOC-VERSION' if necessary, and
  487.      runs `substitute-command-keys' to substitute the actual (current)
  488.      key bindings.
  489.           (documentation-property 'command-line-processed
  490.              'variable-documentation)
  491.                => "t once command line has been processed"
  492.           (symbol-plist 'command-line-processed)
  493.                => (variable-documentation 188902)
  494.  -- Function: documentation FUNCTION
  495.      This function returns the documentation string of FUNCTION.  If
  496.      the documentation string is stored in the `emacs/etc/DOC-VERSION'
  497.      file, this function will access it there.
  498.      In addition, `documentation' runs `substitute-command-keys' on the
  499.      resulting string, so the value contains the actual (current) key
  500.      bindings.
  501.      The function `documentation' signals a `void-function' error
  502.      unless FUNCTION has a function definition.  However, FUNCTION does
  503.      not need to have a documentation string.  If there is no
  504.      documentation string, `documentation' returns `nil'.
  505.      Here is an example of using `documentation' and
  506.      `documentation-property' to display the documentation strings for
  507.      several symbols in a `*Help*' buffer.
  508.           (defun describe-symbols (pattern)
  509.             "Describe the Emacs Lisp symbols matching PATTERN.
  510.           All symbols that have PATTERN in their name are described
  511.           in the *Help* buffer."
  512.             (interactive "sDescribe symbols matching: ")
  513.             (let ((describe-func
  514.                    (function
  515.                     (lambda (s)
  516.                       ;; Print description of symbol.
  517.                       (if (fboundp s)             ; It is a function.
  518.                           (princ
  519.                            (format "%s\t%s\n%s\n\n" s
  520.                                    (if (commandp s)
  521.                                        (concat "Command: "
  522.                                                (or (mapconcat
  523.                                                     'key-description
  524.                                                     (where-is-internal s)
  525.                                                     " ")))
  526.                                      "Function")
  527.                                    (or (documentation s)
  528.                                        "not documented"))))
  529.           
  530.                       (if (boundp s)              ; It is a variable.
  531.                           (princ
  532.                            (format "%s\t%s\n%s\n\n" s
  533.                                    (if (user-variable-p s)
  534.                                        "Option " "Variable")
  535.                                    (or (documentation-property
  536.                                          s 'variable-documentation)
  537.                                        "not documented")))))))
  538.                    sym-list)
  539.           
  540.               ;; Build a list of symbols that match pattern.
  541.               (mapatoms (function
  542.                          (lambda (sym)
  543.                            (if (string-match pattern (symbol-name sym))
  544.                                (setq sym-list (cons sym sym-list))))))
  545.           
  546.               ;; Display the data.
  547.               (with-output-to-temp-buffer "*Help*"
  548.                 (mapcar describe-func (sort sym-list 'string<))
  549.                 (print-help-return-message))))
  550.      The `describe-symbols' function works like `apropos', but provides
  551.      more information.
  552.           (describe-symbols "goal")
  553.           
  554.           ---------- Buffer: *Help* ----------
  555.           goal-column     Option
  556.           *Semipermanent goal column for vertical motion,
  557.           as set by C-x C-n, or nil.
  558.           
  559.           set-goal-column Command: C-x C-n
  560.           Set the current horizontal position as a goal for C-n and C-p.
  561.           Those commands will move to this position in the line moved to
  562.           rather than trying to keep the same horizontal position.
  563.           With a non-nil argument, clears out the goal column
  564.           so that C-n and C-p resume vertical motion.
  565.           
  566.           temporary-goal-column   Variable
  567.           Current goal column for vertical motion.
  568.           It is the column where point was at the start of current run
  569.           of vertical motion commands.
  570.           ---------- Buffer: *Help* ----------
  571.  -- Function: Snarf-documentation FILENAME
  572.      This function is used only during Emacs initialization, just before
  573.      the runnable Emacs is dumped.  It finds the file offsets of the
  574.      documentation strings stored in the file FILENAME, and records
  575.      them in the in-core function definitions and variable property
  576.      lists in place of the actual strings.  *Note Building Emacs::.
  577.      The file FILENAME is found in the `emacs/etc' directory (usually
  578.      FILENAME is `"DOC-VERSION"').  When the dumped Emacs is later
  579.      executed, the same file is found in the `exec-directory' (*note
  580.      Subprocess Creation::.).
  581. File: elisp,  Node: Keys in Documentation,  Next: Describing Characters,  Prev: Accessing Documentation,  Up: Documentation
  582. Substituting Key Bindings in Documentation
  583. ==========================================
  584.  -- Function: substitute-command-keys STRING
  585.      This function returns STRING with certain special substrings
  586.      replaced by the actual (current) key bindings are listed.  This
  587.      permits the documentation to be displayed with accurate
  588.      information about key bindings.  (The key bindings may be changed
  589.      by the user between the time Emacs is built and the time that the
  590.      documentation is asked for.)
  591.      This table lists the forms of the special substrings and what they
  592.      are replaced with:
  593.     `\[COMMAND]'
  594.           is replaced either by a keystroke sequence that will invoke
  595.           COMMAND, or by `M-x COMMAND' if COMMAND is not bound to any
  596.           key sequence.
  597.     `\{MAPVAR}'
  598.           is replaced by a summary (made by `describe-bindings') of the
  599.           value of MAPVAR, taken as a keymap.
  600.     `\<MAPVAR>'
  601.           makes this call to `substitute-command-keys' use the value of
  602.           MAPVAR as the keymap for future `\[COMMAND]' substrings. 
  603.           This special string does not produce any replacement text
  604.           itself; it only affects the replacements done later.
  605.      *Note:* each `\' must be doubled when written in a string in Emacs
  606.      Lisp.
  607.      Here are examples of the special substrings:
  608.           (substitute-command-keys
  609.              "To abort recursive edit, type: \\[abort-recursive-edit]")
  610.           
  611.           => "To abort recursive edit, type: C-]"
  612.           
  613.           (substitute-command-keys
  614.              "The keys that are defined for the minibuffer here are:
  615.             \\{minibuffer-local-must-match-map}")
  616.           
  617.           => "The keys that are defined for the minibuffer here are:
  618.           
  619.           ?               minibuffer-completion-help
  620.           SPC             minibuffer-complete-word
  621.           TAB             minibuffer-complete
  622.           LFD             minibuffer-complete-and-exit
  623.           RET             minibuffer-complete-and-exit
  624.           C-g             abort-recursive-edit
  625.           "
  626.           
  627.           (substitute-command-keys
  628.              "To abort a recursive edit from the minibuffer, type\
  629.            \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
  630.           => "To abort a recursive edit from the minibuffer, type C-g."
  631. File: elisp,  Node: Describing Characters,  Next: Help Functions,  Prev: Keys in Documentation,  Up: Documentation
  632. Describing Characters for Help Messages
  633. =======================================
  634.    These functions convert characters or strings to textual
  635. descriptions. These descriptions are useful for including arbitrary
  636. text characters or key sequences in messages, because they convert
  637. non-printing characters to sequences of printing characters.  The
  638. description of a printing character is the character itself.
  639.  -- Function: key-description STRING
  640.      This function returns a string containing the Emacs standard
  641.      notation for the keyboard characters in STRING.  See the examples
  642.      for `single-key-description'.
  643.  -- Function: single-key-description CHARACTER
  644.      This function returns a string describing CHARACTER in the
  645.      standard Emacs notation for keyboard input.  A normal printing
  646.      character is represented by itself, but a control character turns
  647.      into a string starting with `C-', a meta character turns into a
  648.      string starting with `M-', and space, linefeed, etc. are
  649.      transformed to `SPC', `LFD', etc.
  650.           (single-key-description ?\C-x)
  651.                => "C-x"
  652.           (key-description "\C-x \M-y \n \t \r \f123")
  653.                => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
  654.  -- Function: text-char-description CHARACTER
  655.      This function returns a string describing CHARACTER in the
  656.      standard Emacs notation for characters that appear in text--like
  657.      `single-key-description', except that that control characters are
  658.      represented with a leading caret (which is how control characters
  659.      in Emacs buffers are usually displayed).
  660.           (text-char-description ?\C-c)
  661.                => "^C"
  662.           (text-char-description ?\M-m)
  663.                => "M-m"
  664.           (text-char-description ?\C-\M-m)
  665.                => "M-^M"
  666. File: elisp,  Node: Help Functions,  Prev: Describing Characters,  Up: Documentation
  667. Help Functions
  668. ==============
  669.    Emacs provides a variety of on-line help functions, all accessible to
  670. the user as subcommands of the prefix `C-h'.  For more information
  671. about them, see *Note Help: (emacs)Help.  Here we describe some
  672. program-level interfaces to the same information.
  673.  -- Command: apropos REGEXP &optional PREDICATE NOPRINT
  674.      This function finds all symbols whose names contain a match for the
  675.      regular expression REGEXP, and returns a list of them.  Normally
  676.      it displays the symbols in a buffer named `*Help*', each with a
  677.      one-line description.  If NOPRINT is non-`nil', it does not
  678.      display them, but just returns the list.
  679.      If PREDICATE is non-`nil', it should be a function to be called on
  680.      each symbol that has matched REGEXP.  Only symbols for which
  681.      PREDICATE returns a non-`nil' value are listed or displayed.
  682.      When you call `apropos' interactively, it prompts for REGEXP in
  683.      the minibuffer.
  684.      In the first of the following examples, `apropos' finds all the
  685.      symbols with names containing `exec'.  They are returned but not
  686.      displayed.  In the second example, it finds and returns only those
  687.      symbols that are also commands; in addition, they are then
  688.      displayed in the `*Help*' buffer.
  689.           (apropos "exec" nil t)
  690.                => (Buffer-menu-execute command-execute exec-directory
  691.               exec-path execute-extended-command execute-kbd-macro
  692.               executing-kbd-macro executing-macro)
  693.           
  694.           (apropos "exec" 'commandp)
  695.                => (Buffer-menu-execute execute-extended-command)
  696.           
  697.           ---------- Buffer: *Help* ----------
  698.           Buffer-menu-execute
  699.             Function: Save and/or delete buffers marked with
  700.             M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
  701.           execute-extended-command      ESC x
  702.             Function: Read function name, then read its arguments and call it.
  703.           ---------- Buffer: *Help* ----------
  704.      The command `C-h a' (`command-apropos') calls `apropos', but
  705.      specifies a PREDICATE to restrict the output to symbols that are
  706.      commands.  The call to `apropos' looks like this:
  707.           (apropos string 'commandp)
  708.  -- Command: help-command
  709.      This command is not a function, but rather a symbol which is
  710.      equivalent to the keymap called `help-map'.  It is defined in
  711.      `help.el' as follows:
  712.           (define-key global-map "\C-h" 'help-command)
  713.           (fset 'help-command help-map)
  714.  -- Variable: help-map
  715.      The value of this variable is a local keymap for characters
  716.      following the Help key, `C-h'.
  717.  -- Function: print-help-return-message &optional FUNCTION
  718.      This function builds a string which is a message explaining how to
  719.      restore the previous state of the windows after a help command. 
  720.      After building the message, it applies FUNCTION to it if FUNCTION
  721.      is non-`nil'.  Otherwise it calls `message' to display it in the
  722.      echo area.
  723.      This function expects to be called inside a
  724.      `with-output-to-temp-buffer' special form, and expects
  725.      `standard-output' to have the value bound by that special form.
  726.      For an example of its use, see the example in the section
  727.      describing the `documentation' function (*note Accessing
  728.      Documentation::.).
  729.      The constructed message will have one of the forms shown below.
  730.           ---------- Echo Area ----------
  731.           Type C-x 1 to remove help window.
  732.           ---------- Echo Area ----------
  733.           
  734.           ---------- Echo Area ----------
  735.           Type C-x 4 b RET to restore old contents of help window.
  736.           ---------- Echo Area ----------
  737.  -- Variable: help-char
  738.      The value of this variable is the character that Emacs recognizes
  739.      as meaning Help.  When Emacs reads this character (which is
  740.      usually 8, the value of `C-h'), Emacs evaluates `(eval
  741.      help-form)', and displays the result if it is a string.  If
  742.      `help-form''s value is `nil', this character is read normally.
  743.  -- Variable: help-form
  744.      The value of this variable is a form to execute when the character
  745.      `help-char' is read.  If the form returns a string, that string is
  746.      displayed.  If `help-form' is `nil', then the help character is
  747.      not recognized.
  748.      Entry to the minibuffer binds this variable to the value of
  749.      `minibuffer-help-form'.
  750.    The following two functions are found in the library `helper'. They
  751. are for modes that want to provide help without relinquishing control,
  752. such as the "electric" modes.  You must load that library with
  753. `(require 'helper)' in order to use them.  Their names begin with
  754. `Helper' to distinguish them from the ordinary help functions.
  755.  -- Command: Helper-describe-bindings
  756.      This command pops up a window displaying a help buffer containing a
  757.      listing of all of the key bindings from both the local and global
  758.      keymaps. It works by calling `describe-bindings'.
  759.  -- Command: Helper-help
  760.      This command provides help for the current mode.  It prompts the
  761.      user in the minibuffer with the message `Help (Type ? for further
  762.      options)', and then provides assistance in finding out what the key
  763.      bindings are, and what the mode is intended for.  It returns `nil'.
  764.      This can be customized by changing the map `Helper-help-map'.
  765. File: elisp,  Node: Files,  Next: Backups and Auto-Saving,  Prev: Documentation,  Up: Top
  766. Files
  767. *****
  768.    In Emacs, you can find, create, view, save, and otherwise work with
  769. files and file directories.  This chapter describes most of the
  770. file-related functions of Emacs Lisp, but a few others are described in
  771. *Note Buffers::, and those related to backups and auto-saving are
  772. described in *Note Backups and Auto-Saving::.
  773. * Menu:
  774. * Visiting Files::           Reading files into Emacs buffers for editing.
  775. * Saving Buffers::           Writing changed buffers back into files.
  776. * Reading from Files::       Reading files into other buffers.
  777. * Writing to Files::         Writing new files from parts of buffers.
  778. * File Locks::               Locking and unlocking files, to prevent
  779.                                simultaneous editing by two people.
  780. * Information about Files::  Testing existence, accessibility, size of files.
  781. * Contents of Directories::  Getting a list of the files in a directory.
  782. * Changing File Attributes:: Renaming files, changing protection, etc.
  783. * File Names::               Decomposing and expanding file names.
  784. File: elisp,  Node: Visiting Files,  Next: Saving Buffers,  Prev: Files,  Up: Files
  785. Visiting Files
  786. ==============
  787.    Visiting a file means reading a file into a buffer.  Once this is
  788. done, we say that the buffer is "visiting" that file, and call the file
  789. "the visited file" of the buffer.
  790.    A file and a buffer are two different things.  A file is information
  791. recorded permanently in the computer (unless you delete it).  A buffer,
  792. on the other hand, is information inside of Emacs that will vanish at
  793. the end of the editing session (or when you kill the buffer).  Usually,
  794. a buffer contains information that you have copied from a file; then we
  795. say the buffer is visiting that file.  The copy in the buffer is what
  796. you modify with editing commands.  Such changes to the buffer do not
  797. change the file; therefore, to make the changes permanent, you must
  798. "save" the buffer, which means copying the altered buffer contents back
  799. into the file.
  800.    In spite of the distinction between files and buffers, people often
  801. refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
  802. "I am editing a file," rather than, "I am editing a buffer which I will
  803. soon save as a file of the same name."  Humans do not usually need to
  804. make the distinction explicit.  When dealing with a computer program,
  805. however, it is good to keep the distinction in mind.
  806. * Menu:
  807. * Visiting Functions::         The usual interface functions for visiting.
  808. * Subroutines of Visiting::    Lower-level subroutines that they use.
  809. File: elisp,  Node: Visiting Functions,  Next: Subroutines of Visiting,  Prev: Visiting Files,  Up: Visiting Files
  810. Functions for Visiting Files
  811. ----------------------------
  812.    This section describes the functions normally used to visit files.
  813. For historical reasons, these functions have names starting with
  814. `find-' rather than `visit-'.  *Note Buffer File Name::, for functions
  815. and variables that access the visited file name of a buffer or that
  816. find an existing buffer by its visited file name.
  817.  -- Command: find-file FILENAME
  818.      This function reads the file FILENAME into a buffer and displays
  819.      that buffer in the selected window so that the user can edit it.
  820.      The body of the `find-file' function is very simple and looks like
  821.      this:
  822.           (switch-to-buffer (find-file-noselect filename))
  823.      (See `switch-to-buffer' in *Note Displaying Buffers::.)
  824.      When `find-file' is called interactively, it prompts for FILENAME
  825.      in the minibuffer.
  826.  -- Function: find-file-noselect FILENAME
  827.      This function is the guts of all the file-visiting functions.  It
  828.      reads a file into a buffer and returns the buffer.  You may then
  829.      make the buffer current or display it in a window if you wish, but
  830.      this function does not do so.
  831.      If no buffer is currently visiting FILENAME, then one is created
  832.      and the file is visited.  If FILENAME does not exist, the buffer
  833.      is left empty, and `find-file-noselect' displays the message `New
  834.      file' in the echo area.
  835.      If a buffer is already visiting FILENAME, then
  836.      `find-file-noselect' uses that buffer rather than creating a new
  837.      one.  However, it does verify that the file has not changed since
  838.      it was last visited or saved in that buffer.  If the file has
  839.      changed, then this function asks the user whether to reread the
  840.      changed file.  If the user says `yes', any changes previously made
  841.      in the buffer will be lost.
  842.      The `find-file-noselect' function calls `after-find-file' after
  843.      the file is read in (*note Subroutines of Visiting::.).  The
  844.      `after-find-file' function sets the buffer major mode, parses local
  845.      variables, warns the user if there exists an auto-save file more
  846.      recent than the file just visited, and finishes by running the
  847.      functions in `find-file-hooks'.
  848.      The `find-file-noselect' function returns the buffer that is
  849.      visiting the file FILENAME.
  850.           (find-file-noselect "/etc/fstab")
  851.                => #<buffer fstab>
  852.  -- Command: find-alternate-file FILENAME
  853.      This function reads the file FILENAME into a buffer and selects
  854.      it, killing the buffer current at the time the command is run.  It
  855.      is useful if you have visited the wrong file by mistake, so that
  856.      you can get rid of the buffer that you did not want to create, at
  857.      the same time as you visit the file you intended.
  858.      When this function is called interactively, it prompts for
  859.      FILENAME.
  860.  -- Command: find-file-other-window FILENAME
  861.      This function visits the file FILENAME and displays its buffer in
  862.      a window other than the selected window.  If there are two or more
  863.      windows on the screen, then the window that is not selected is
  864.      used.  If there is only one window, it is split.  The function
  865.      returns `nil'.
  866.      When this function is called interactively, it prompts for
  867.      FILENAME.
  868.  -- Command: find-file-read-only FILENAME
  869.      This function visits the file named FILENAME and selects its
  870.      buffer, just like `find-file', but it marks the buffer as
  871.      read-only.  *Note Read Only Buffers::, for related functions and
  872.      variables.
  873.      When this function is called interactively, it prompts for
  874.      FILENAME.
  875.  -- Command: view-file FILENAME
  876.      This function views FILENAME in View mode, returning to the
  877.      previous buffer when done.  View mode is a mode that allows you to
  878.      skim rapidly through the file but does not let you modify it.
  879.      After loading the file, `view-file' calls the value of `view-hook'
  880.      if that is non-`nil'.
  881.      When this function is called interactively, it prompts for
  882.      FILENAME.
  883.  -- Variable: find-file-hooks
  884.      The value of this variable is a list of functions to be called
  885.      after a file is visited.  The file's local-variables specification
  886.      (if any) will have been processed before the hooks are run.  The
  887.      buffer visiting the file is current when the hook functions are
  888.      run.
  889.  -- Variable: find-file-not-found-hooks
  890.      The value of this variable is a list of functions to be called when
  891.      `find-file' or `find-file-noselect' is passed a nonexistent
  892.      FILENAME.  These functions are called as soon as the error is
  893.      detected.  `buffer-file-name' is already set up.  The functions are
  894.      called in the order given, until one of them returns non-`nil'.
  895. File: elisp,  Node: Subroutines of Visiting,  Prev: Visiting Functions,  Up: Visiting Files
  896. Subroutines of Visiting
  897. -----------------------
  898.    The `find-file-noselect' function uses the `create-file-buffer' and
  899. `after-find-file' functions as subroutines.  Sometimes it is useful to
  900. call them directly.
  901.  -- Function: create-file-buffer FILENAME
  902.      This function creates a suitably named buffer for visiting
  903.      FILENAME, and returns it.  The string FILENAME (sans directory) is
  904.      used unchanged if that name is free; otherwise, a string such as
  905.      `<2>' is appended to get an unused name.  See also *Note Creating
  906.      Buffers::.
  907.      *Note:* `create-file-buffer' does *not* associate the new buffer
  908.      with a file and does not make it the current buffer.
  909.           (create-file-buffer "foo")
  910.                => #<buffer foo>
  911.           (create-file-buffer "foo")
  912.                => #<buffer foo<2>>
  913.           (create-file-buffer "foo")
  914.                => #<buffer foo<3>>
  915.      This function is used by `find-file-noselect'.
  916.  -- Function: after-find-file &optional ERROR WARN
  917.      This function is called by `find-file-noselect' and by the default
  918.      revert function (*note Reverting::.).  It sets the buffer major
  919.      mode, and parses local variables (*note Auto Major Mode::.).
  920.      If there was an error in opening the file, the calling function
  921.      should pass ERROR a non-`nil' value.  In that case,
  922.      `after-find-file' issues a warning: `(New File)'.  Note that, for
  923.      serious errors, you would not even call `after-find-file'. Only
  924.      "file not found" errors get here with a non-`nil' ERROR.
  925.      If WARN is non-`nil', then this function issues a warning if an
  926.      auto-save file exists and is more recent than the visited file.
  927.      The last thing `after-find-file' does is call all the functions in
  928.      `find-file-hooks'.
  929.