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