-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes
+
+Getting Help about a Major Mode
+-------------------------------
+
+ The `describe-mode' function is used to provide information about
+major modes. It is normally called with `C-h m'. The `describe-mode'
+function uses the value of `major-mode', which is why every major mode
+function needs to set the `major-mode' variable.
+
+ - Command: describe-mode
+ This function displays the documentation of the current major mode.
+
+ The `describe-mode' function calls the `documentation' function
+ using the value of `major-mode' as an argument. Thus, it displays
+ the documentation string of the major mode function. (*Note
+ Accessing Documentation::.)
+
+ - Variable: major-mode
+ This variable holds the symbol for the current buffer's major mode.
+ This symbol should have a function definition that is the command
+ to switch to that major mode. The `describe-mode' function uses
+ the documentation string of the function as the documentation of
+ the major mode.
+
+\1f
+File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes
+
+Defining Derived Modes
+----------------------
+
+ It's often useful to define a new major mode in terms of an existing
+one. An easy way to do this is to use `define-derived-mode'.
+
+ - Macro: define-derived-mode variant parent name docstring body...
+ This construct defines VARIANT as a major mode command, using NAME
+ as the string form of the mode name.
+
+ The new command VARIANT is defined to call the function PARENT,
+ then override certain aspects of that parent mode:
+
+ * The new mode has its own keymap, named `VARIANT-map'.
+ `define-derived-mode' initializes this map to inherit from
+ `PARENT-map', if it is not already set.
+
+ * The new mode has its own syntax table, kept in the variable
+ `VARIANT-syntax-table'. `define-derived-mode' initializes
+ this variable by copying `PARENT-syntax-table', if it is not
+ already set.
+
+ * The new mode has its own abbrev table, kept in the variable
+ `VARIANT-abbrev-table'. `define-derived-mode' initializes
+ this variable by copying `PARENT-abbrev-table', if it is not
+ already set.
+
+ * The new mode has its own mode hook, `VARIANT-hook', which it
+ runs in standard fashion as the very last thing that it does.
+ (The new mode also runs the mode hook of PARENT as part of
+ calling PARENT.)
+
+ In addition, you can specify how to override other aspects of
+ PARENT with BODY. The command VARIANT evaluates the forms in BODY
+ after setting up all its usual overrides, just before running
+ `VARIANT-hook'.
+
+ The argument DOCSTRING specifies the documentation string for the
+ new mode. If you omit DOCSTRING, `define-derived-mode' generates
+ a documentation string.
+
+ Here is a hypothetical example:
+
+ (define-derived-mode hypertext-mode
+ text-mode "Hypertext"
+ "Major mode for hypertext.
+ \\{hypertext-mode-map}"
+ (setq case-fold-search nil))
+
+ (define-key hypertext-mode-map
+ [down-mouse-3] 'do-hyper-link)
+
+\1f
+File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes
+
+Minor Modes
+===========
+
+ A "minor mode" provides features that users may enable or disable
+independently of the choice of major mode. Minor modes can be enabled
+individually or in combination. Minor modes would be better named
+"Generally available, optional feature modes" except that such a name is
+unwieldy.
+
+ A minor mode is not usually a modification of single major mode. For
+example, Auto Fill mode may be used in any major mode that permits text
+insertion. To be general, a minor mode must be effectively independent
+of the things major modes do.
+
+ A minor mode is often much more difficult to implement than a major
+mode. One reason is that you should be able to activate and deactivate
+minor modes in any order. A minor mode should be able to have its
+desired effect regardless of the major mode and regardless of the other
+minor modes in effect.
+
+ Often the biggest problem in implementing a minor mode is finding a
+way to insert the necessary hook into the rest of XEmacs. Minor mode
+keymaps make this easier than it used to be.
+
+* Menu:
+
+* Minor Mode Conventions:: Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+
+\1f
+File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes
+
+Conventions for Writing Minor Modes
+-----------------------------------
+
+ There are conventions for writing minor modes just as there are for
+major modes. Several of the major mode conventions apply to minor
+modes as well: those regarding the name of the mode initialization
+function, the names of global symbols, and the use of keymaps and other
+tables.
+
+ In addition, there are several conventions that are specific to
+minor modes.
+
+ * Make a variable whose name ends in `-mode' to represent the minor
+ mode. Its value should enable or disable the mode (`nil' to
+ disable; anything else to enable.) We call this the "mode
+ variable".
+
+ This variable is used in conjunction with the `minor-mode-alist' to
+ display the minor mode name in the modeline. It can also enable
+ or disable a minor mode keymap. Individual commands or hooks can
+ also check the variable's value.
+
+ If you want the minor mode to be enabled separately in each buffer,
+ make the variable buffer-local.
+
+ * Define a command whose name is the same as the mode variable. Its
+ job is to enable and disable the mode by setting the variable.
+
+ The command should accept one optional argument. If the argument
+ is `nil', it should toggle the mode (turn it on if it is off, and
+ off if it is on). Otherwise, it should turn the mode on if the
+ argument is a positive integer, a symbol other than `nil' or `-',
+ or a list whose CAR is such an integer or symbol; it should turn
+ the mode off otherwise.
+
+ Here is an example taken from the definition of
+ `transient-mark-mode'. It shows the use of `transient-mark-mode'
+ as a variable that enables or disables the mode's behavior, and
+ also shows the proper way to toggle, enable or disable the minor
+ mode based on the raw prefix argument value.
+
+ (setq transient-mark-mode
+ (if (null arg) (not transient-mark-mode)
+ (> (prefix-numeric-value arg) 0)))
+
+ * Add an element to `minor-mode-alist' for each minor mode (*note
+ Modeline Variables::). This element should be a list of the
+ following form:
+
+ (MODE-VARIABLE STRING)
+
+ Here MODE-VARIABLE is the variable that controls enabling of the
+ minor mode, and STRING is a short string, starting with a space,
+ to represent the mode in the modeline. These strings must be
+ short so that there is room for several of them at once.
+
+ When you add an element to `minor-mode-alist', use `assq' to check
+ for an existing element, to avoid duplication. For example:
+
+ (or (assq 'leif-mode minor-mode-alist)
+ (setq minor-mode-alist
+ (cons '(leif-mode " Leif") minor-mode-alist)))
+
+\1f
+File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes
+
+Keymaps and Minor Modes
+-----------------------
+
+ Each minor mode can have its own keymap, which is active when the
+mode is enabled. To set up a keymap for a minor mode, add an element
+to the alist `minor-mode-map-alist'. *Note Active Keymaps::.
+
+ One use of minor mode keymaps is to modify the behavior of certain
+self-inserting characters so that they do something else as well as
+self-insert. In general, this is the only way to do that, since the
+facilities for customizing `self-insert-command' are limited to special
+cases (designed for abbrevs and Auto Fill mode). (Do not try
+substituting your own definition of `self-insert-command' for the
+standard one. The editor command loop handles this function specially.)
+
+\1f
+File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes
+
+Modeline Format
+===============
+
+ Each Emacs window (aside from minibuffer windows) includes a
+modeline, which displays status information about the buffer displayed
+in the window. The modeline contains information about the buffer,
+such as its name, associated file, depth of recursive editing, and the
+major and minor modes.
+
+ This section describes how the contents of the modeline are
+controlled. It is in the chapter on modes because much of the
+information displayed in the modeline relates to the enabled major and
+minor modes.
+
+ `modeline-format' is a buffer-local variable that holds a template
+used to display the modeline of the current buffer. All windows for
+the same buffer use the same `modeline-format' and their modelines
+appear the same (except for scrolling percentages and line numbers).
+
+ The modeline of a window is normally updated whenever a different
+buffer is shown in the window, or when the buffer's modified-status
+changes from `nil' to `t' or vice-versa. If you modify any of the
+variables referenced by `modeline-format' (*note Modeline Variables::),
+you may want to force an update of the modeline so as to display the
+new information.
+
+ - Function: redraw-modeline &optional all
+ Force redisplay of the current buffer's modeline. If ALL is
+ non-`nil', then force redisplay of all modelines.
+
+ The modeline is usually displayed in inverse video. This is
+controlled using the `modeline' face. *Note Faces::.
+
+* Menu:
+
+* Modeline Data:: The data structure that controls the modeline.
+* Modeline Variables:: Variables used in that data structure.
+* %-Constructs:: Putting information into a modeline.
+
+\1f
+File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format
+
+The Data Structure of the Modeline
+----------------------------------
+
+ The modeline contents are controlled by a data structure of lists,
+strings, symbols, and numbers kept in the buffer-local variable
+`modeline-format'. The data structure is called a "modeline
+construct", and it is built in recursive fashion out of simpler modeline
+constructs. The same data structure is used for constructing frame
+titles (*note Frame Titles::).
+
+ - Variable: modeline-format
+ The value of this variable is a modeline construct with overall
+ responsibility for the modeline format. The value of this variable
+ controls which other variables are used to form the modeline text,
+ and where they appear.
+
+ A modeline construct may be as simple as a fixed string of text, but
+it usually specifies how to use other variables to construct the text.
+Many of these variables are themselves defined to have modeline
+constructs as their values.
+
+ The default value of `modeline-format' incorporates the values of
+variables such as `mode-name' and `minor-mode-alist'. Because of this,
+very few modes need to alter `modeline-format'. For most purposes, it
+is sufficient to alter the variables referenced by `modeline-format'.
+
+ A modeline construct may be a string, symbol, glyph, generic
+specifier, list or cons cell.
+
+`STRING'
+ A string as a modeline construct is displayed verbatim in the mode
+ line except for "`%'-constructs". Decimal digits after the `%'
+ specify the field width for space filling on the right (i.e., the
+ data is left justified). *Note %-Constructs::.
+
+`SYMBOL'
+ A symbol as a modeline construct stands for its value. The value
+ of SYMBOL is processed as a modeline construct, in place of
+ SYMBOL. However, the symbols `t' and `nil' are ignored; so is any
+ symbol whose value is void.
+
+ There is one exception: if the value of SYMBOL is a string, it is
+ displayed verbatim: the `%'-constructs are not recognized.
+
+`GLYPH'
+ A glyph is displayed as is.
+
+`GENERIC-SPECIFIER'
+ A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands
+ for its instance. The instance of GENERIC-SPECIFIER is computed
+ in the current window using the equivalent of `specifier-instance'
+ and the value is processed.
+
+`(STRING REST...) or (LIST REST...)'
+ A list whose first element is a string or list means to process
+ all the elements recursively and concatenate the results. This is
+ the most common form of mode line construct.
+
+`(SYMBOL THEN ELSE)'
+ A list whose first element is a symbol is a conditional. Its
+ meaning depends on the value of SYMBOL. If the value is non-`nil',
+ the second element, THEN, is processed recursively as a modeline
+ element. But if the value of SYMBOL is `nil', the third element,
+ ELSE, is processed recursively. You may omit ELSE; then the mode
+ line element displays nothing if the value of SYMBOL is `nil'.
+
+`(WIDTH REST...)'
+ A list whose first element is an integer specifies truncation or
+ padding of the results of REST. The remaining elements REST are
+ processed recursively as modeline constructs and concatenated
+ together. Then the result is space filled (if WIDTH is positive)
+ or truncated (to -WIDTH columns, if WIDTH is negative) on the
+ right.
+
+ For example, the usual way to show what percentage of a buffer is
+ above the top of the window is to use a list like this: `(-3
+ "%p")'.
+
+`(EXTENT REST...)'
+ A list whose car is an extent means the cdr of the list is
+ processed normally but the results are displayed using the face of
+ the extent, and mouse clicks over this section are processed using
+ the keymap of the extent. (In addition, if the extent has a
+ help-echo property, that string will be echoed when the mouse
+ moves over this section.) If extents are nested, all keymaps are
+ properly consulted when processing mouse clicks, but multiple
+ faces are not correctly merged (only the first face is used), and
+ lists of faces are not correctly handled.
+
+ If you do alter `modeline-format' itself, the new value should use
+the same variables that appear in the default value (*note Modeline
+Variables::), rather than duplicating their contents or displaying the
+information in another fashion. This way, customizations made by the
+user or by Lisp programs (such as `display-time' and major modes) via
+changes to those variables remain effective.
+
+ Here is an example of a `modeline-format' that might be useful for
+`shell-mode', since it contains the hostname and default directory.
+
+ (setq modeline-format
+ (list ""
+ 'modeline-modified
+ "%b--"
+ (getenv "HOST") ; One element is not constant.
+ ":"
+ 'default-directory
+ " "
+ 'global-mode-string
+ " %[("
+ 'mode-name
+ 'modeline-process
+ 'minor-mode-alist
+ "%n"
+ ")%]----"
+ '(line-number-mode "L%l--")
+ '(-3 . "%p")
+ "-%-"))
+
+\1f
+File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format
+
+Variables Used in the Modeline
+------------------------------
+
+ This section describes variables incorporated by the standard value
+of `modeline-format' into the text of the mode line. There is nothing
+inherently special about these variables; any other variables could
+have the same effects on the modeline if `modeline-format' were changed
+to use them.
+
+ - Variable: modeline-modified
+ This variable holds the value of the modeline construct that
+ displays whether the current buffer is modified.
+
+ The default value of `modeline-modified' is `("--%1*%1+-")'. This
+ means that the modeline displays `--**-' if the buffer is
+ modified, `-----' if the buffer is not modified, `--%%-' if the
+ buffer is read only, and `--%*--' if the buffer is read only and
+ modified.
+
+ Changing this variable does not force an update of the modeline.
+
+ - Variable: modeline-buffer-identification
+ This variable identifies the buffer being displayed in the window.
+ Its default value is `("%F: %17b")', which means that it usually
+ displays `Emacs:' followed by seventeen characters of the buffer
+ name. (In a terminal frame, it displays the frame name instead of
+ `Emacs'; this has the effect of showing the frame number.) You may
+ want to change this in modes such as Rmail that do not behave like
+ a "normal" XEmacs.
+
+ - Variable: global-mode-string
+ This variable holds a modeline spec that appears in the mode line
+ by default, just after the buffer name. The command `display-time'
+ sets `global-mode-string' to refer to the variable
+ `display-time-string', which holds a string containing the time and
+ load information.
+
+ The `%M' construct substitutes the value of `global-mode-string',
+ but this is obsolete, since the variable is included directly in
+ the modeline.
+
+ - Variable: mode-name
+ This buffer-local variable holds the "pretty" name of the current
+ buffer's major mode. Each major mode should set this variable so
+ that the mode name will appear in the modeline.
+
+ - Variable: minor-mode-alist
+ This variable holds an association list whose elements specify how
+ the modeline should indicate that a minor mode is active. Each
+ element of the `minor-mode-alist' should be a two-element list:
+
+ (MINOR-MODE-VARIABLE MODELINE-STRING)
+
+ More generally, MODELINE-STRING can be any mode line spec. It
+ appears in the mode line when the value of MINOR-MODE-VARIABLE is
+ non-`nil', and not otherwise. These strings should begin with
+ spaces so that they don't run together. Conventionally, the
+ MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
+ value when that minor mode is activated.
+
+ The default value of `minor-mode-alist' is:
+
+ minor-mode-alist
+ => ((vc-mode vc-mode)
+ (abbrev-mode " Abbrev")
+ (overwrite-mode overwrite-mode)
+ (auto-fill-function " Fill")
+ (defining-kbd-macro " Def")
+ (isearch-mode isearch-mode))
+
+ `minor-mode-alist' is not buffer-local. The variables mentioned
+ in the alist should be buffer-local if the minor mode can be
+ enabled separately in each buffer.
+
+ - Variable: modeline-process
+ This buffer-local variable contains the modeline information on
+ process status in modes used for communicating with subprocesses.
+ It is displayed immediately following the major mode name, with no
+ intervening space. For example, its value in the `*shell*' buffer
+ is `(": %s")', which allows the shell to display its status along
+ with the major mode as: `(Shell: run)'. Normally this variable is
+ `nil'.
+
+ - Variable: default-modeline-format
+ This variable holds the default `modeline-format' for buffers that
+ do not override it. This is the same as `(default-value
+ 'modeline-format)'.
+
+ The default value of `default-modeline-format' is:
+
+ (""
+ modeline-modified
+ modeline-buffer-identification
+ " "
+ global-mode-string
+ " %[("
+ mode-name
+ modeline-process
+ minor-mode-alist
+ "%n"
+ ")%]----"
+ (line-number-mode "L%l--")
+ (-3 . "%p")
+ "-%-")
+
+ - Variable: vc-mode
+ The variable `vc-mode', local in each buffer, records whether the
+ buffer's visited file is maintained with version control, and, if
+ so, which kind. Its value is `nil' for no version control, or a
+ string that appears in the mode line.
+
+\1f
+File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
+
+`%'-Constructs in the ModeLine
+------------------------------
+
+ The following table lists the recognized `%'-constructs and what
+they mean. In any construct except `%%', you can add a decimal integer
+after the `%' to specify how many characters to display.
+
+`%b'
+ The current buffer name, obtained with the `buffer-name' function.
+ *Note Buffer Names::.
+
+`%f'
+ The visited file name, obtained with the `buffer-file-name'
+ function. *Note Buffer File Name::.
+
+`%F'
+ The name of the selected frame.
+
+`%c'
+ The current column number of point.
+
+`%l'
+ The current line number of point.
+
+`%*'
+ `%' if the buffer is read only (see `buffer-read-only');
+ `*' if the buffer is modified (see `buffer-modified-p');
+ `-' otherwise. *Note Buffer Modification::.
+
+`%+'
+ `*' if the buffer is modified (see `buffer-modified-p');
+ `%' if the buffer is read only (see `buffer-read-only');
+ `-' otherwise. This differs from `%*' only for a modified
+ read-only buffer. *Note Buffer Modification::.
+
+`%&'
+ `*' if the buffer is modified, and `-' otherwise.
+
+`%s'
+ The status of the subprocess belonging to the current buffer,
+ obtained with `process-status'. *Note Process Information::.
+
+`%l'
+ The current line number.
+
+`%S'
+ The name of the selected frame; this is only meaningful under the
+ X Window System. *Note Frame Name::.
+
+`%t'
+ Whether the visited file is a text file or a binary file. (This
+ is a meaningful distinction only on certain operating systems.)
+
+`%p'
+ The percentage of the buffer text above the *top* of window, or
+ `Top', `Bottom' or `All'.
+
+`%P'
+ The percentage of the buffer text that is above the *bottom* of
+ the window (which includes the text visible in the window, as well
+ as the text above the top), plus `Top' if the top of the buffer is
+ visible on screen; or `Bottom' or `All'.
+
+`%n'
+ `Narrow' when narrowing is in effect; nothing otherwise (see
+ `narrow-to-region' in *Note Narrowing::).
+
+`%C'
+ Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.
+
+`%['
+ An indication of the depth of recursive editing levels (not
+ counting minibuffer levels): one `[' for each editing level.
+ *Note Recursive Editing::.
+
+`%]'
+ One `]' for each recursive editing level (not counting minibuffer
+ levels).
+
+`%%'
+ The character `%'--this is how to include a literal `%' in a
+ string in which `%'-constructs are allowed.
+
+`%-'
+ Dashes sufficient to fill the remainder of the modeline.
+
+ The following two `%'-constructs are still supported, but they are
+obsolete, since you can get the same results with the variables
+`mode-name' and `global-mode-string'.
+
+`%m'
+ The value of `mode-name'.
+
+`%M'
+ The value of `global-mode-string'. Currently, only `display-time'
+ modifies the value of `global-mode-string'.
+
+\1f
+File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
+
+Hooks
+=====
+
+ A "hook" is a variable where you can store a function or functions
+to be called on a particular occasion by an existing program. XEmacs
+provides hooks for the sake of customization. Most often, hooks are set
+up in the `.emacs' file, but Lisp programs can set them also. *Note
+Standard Hooks::, for a list of standard hook variables.
+
+ Most of the hooks in XEmacs are "normal hooks". These variables
+contain lists of functions to be called with no arguments. The reason
+most hooks are normal hooks is so that you can use them in a uniform
+way. You can usually tell when a hook is a normal hook, because its
+name ends in `-hook'.
+
+ The recommended way to add a hook function to a normal hook is by
+calling `add-hook' (see below). The hook functions may be any of the
+valid kinds of functions that `funcall' accepts (*note What Is a
+Function::). Most normal hook variables are initially void; `add-hook'
+knows how to deal with this.
+
+ As for abnormal hooks, those whose names end in `-function' have a
+value that is a single function. Those whose names end in `-hooks'
+have a value that is a list of functions. Any hook that is abnormal is
+abnormal because a normal hook won't do the job; either the functions
+are called with arguments, or their values are meaningful. The name
+shows you that the hook is abnormal and that you should look at its
+documentation string to see how to use it properly.
+
+ Major mode functions are supposed to run a hook called the "mode
+hook" as the last step of initialization. This makes it easy for a user
+to customize the behavior of the mode, by overriding the local variable
+assignments already made by the mode. But hooks are used in other
+contexts too. For example, the hook `suspend-hook' runs just before
+XEmacs suspends itself (*note Suspending XEmacs::).
+
+ Here's an expression that uses a mode hook to turn on Auto Fill mode
+when in Lisp Interaction mode:
+
+ (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+
+ The next example shows how to use a hook to customize the way XEmacs
+formats C code. (People often have strong personal preferences for one
+format or another.) Here the hook function is an anonymous lambda
+expression.
+
+ (add-hook 'c-mode-hook
+ (function (lambda ()
+ (setq c-indent-level 4
+ c-argdecl-indent 0
+ c-label-offset -4
+ c-continued-statement-indent 0
+ c-brace-offset 0
+ comment-column 40))))
+
+ (setq c++-mode-hook c-mode-hook)
+
+ The final example shows how the appearance of the modeline can be
+modified for a particular class of buffers only.
+
+ (add-hook 'text-mode-hook
+ (function (lambda ()
+ (setq modeline-format
+ '(modeline-modified
+ "Emacs: %14b"
+ " "
+ default-directory
+ " "
+ global-mode-string
+ "%[("
+ mode-name
+ minor-mode-alist
+ "%n"
+ modeline-process
+ ") %]---"
+ (-3 . "%p")
+ "-%-")))))
+
+ At the appropriate time, XEmacs uses the `run-hooks' function to run
+particular hooks. This function calls the hook functions you have
+added with `add-hooks'.
+
+ - Function: run-hooks &rest hookvar
+ This function takes one or more hook variable names as arguments,
+ and runs each hook in turn. Each HOOKVAR argument should be a
+ symbol that is a hook variable. These arguments are processed in
+ the order specified.
+
+ If a hook variable has a non-`nil' value, that value may be a
+ function or a list of functions. If the value is a function
+ (either a lambda expression or a symbol with a function
+ definition), it is called. If it is a list, the elements are
+ called, in order. The hook functions are called with no arguments.
+
+ For example, here's how `emacs-lisp-mode' runs its mode hook:
+
+ (run-hooks 'emacs-lisp-mode-hook)
+
+ - Function: add-hook hook function &optional append local
+ This function is the handy way to add function FUNCTION to hook
+ variable HOOK. The argument FUNCTION may be any valid Lisp
+ function with the proper number of arguments. For example,
+
+ (add-hook 'text-mode-hook 'my-text-hook-function)
+
+ adds `my-text-hook-function' to the hook called `text-mode-hook'.
+
+ You can use `add-hook' for abnormal hooks as well as for normal
+ hooks.
+
+ It is best to design your hook functions so that the order in
+ which they are executed does not matter. Any dependence on the
+ order is "asking for trouble." However, the order is predictable:
+ normally, FUNCTION goes at the front of the hook list, so it will
+ be executed first (barring another `add-hook' call).
+
+ If the optional argument APPEND is non-`nil', the new hook
+ function goes at the end of the hook list and will be executed
+ last.
+
+ If LOCAL is non-`nil', that says to make the new hook function
+ local to the current buffer. Before you can do this, you must
+ make the hook itself buffer-local by calling `make-local-hook'
+ (*not* `make-local-variable'). If the hook itself is not
+ buffer-local, then the value of LOCAL makes no difference--the
+ hook function is always global.
+
+ - Function: remove-hook hook function &optional local
+ This function removes FUNCTION from the hook variable HOOK.
+
+ If LOCAL is non-`nil', that says to remove FUNCTION from the local
+ hook list instead of from the global hook list. If the hook
+ itself is not buffer-local, then the value of LOCAL makes no
+ difference.
+
+ - Function: make-local-hook hook
+ This function makes the hook variable HOOK local to the current
+ buffer. When a hook variable is local, it can have local and
+ global hook functions, and `run-hooks' runs all of them.
+
+ This function works by making `t' an element of the buffer-local
+ value. That serves as a flag to use the hook functions in the
+ default value of the hook variable as well as those in the local
+ value. Since `run-hooks' understands this flag, `make-local-hook'
+ works with all normal hooks. It works for only some non-normal
+ hooks--those whose callers have been updated to understand this
+ meaning of `t'.
+
+ Do not use `make-local-variable' directly for hook variables; it is
+ not sufficient.
+
+\1f
+File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
+
+Documentation
+*************
+
+ XEmacs Lisp has convenient on-line help facilities, most of which
+derive their information from the documentation strings associated with
+functions and variables. This chapter describes how to write good
+documentation strings for your Lisp programs, as well as how to write
+programs to access documentation.
+
+ Note that the documentation strings for XEmacs are not the same thing
+as the XEmacs manual. Manuals have their own source files, written in
+the Texinfo language; documentation strings are specified in the
+definitions of the functions and variables they apply to. A collection
+of documentation strings is not sufficient as a manual because a good
+manual is not organized in that fashion; it is organized in terms of
+topics of discussion.
+
+* Menu:
+
+* Documentation Basics:: Good style for doc strings.
+ Where to put them. How XEmacs stores them.
+* Accessing Documentation:: How Lisp programs can access doc strings.
+* Keys in Documentation:: Substituting current key bindings.
+* Describing Characters:: Making printable descriptions of
+ non-printing characters and key sequences.
+* Help Functions:: Subroutines used by XEmacs help facilities.
+* Obsoleteness:: Upgrading Lisp functionality over time.
+
+\1f
+File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
+
+Documentation Basics
+====================
+
+ A documentation string is written using the Lisp syntax for strings,
+with double-quote characters surrounding the text of the string. This
+is because it really is a Lisp string object. The string serves as
+documentation when it is written in the proper place in the definition
+of a function or variable. In a function definition, the documentation
+string follows the argument list. In a variable definition, the
+documentation string follows the initial value of the variable.
+
+ When you write a documentation string, make the first line a complete
+sentence (or two complete sentences) since some commands, such as
+`apropos', show only the first line of a multi-line documentation
+string. Also, you should not indent the second line of a documentation
+string, if you have one, because that looks odd when you use `C-h f'
+(`describe-function') or `C-h v' (`describe-variable'). *Note
+Documentation Tips::.
+
+ Documentation strings may contain several special substrings, which
+stand for key bindings to be looked up in the current keymaps when the
+documentation is displayed. This allows documentation strings to refer
+to the keys for related commands and be accurate even when a user
+rearranges the key bindings. (*Note Accessing Documentation::.)
+
+ Within the Lisp world, a documentation string is accessible through
+the function or variable that it describes:
+
+ * The documentation for a function is stored in the function
+ definition itself (*note Lambda Expressions::). The function
+ `documentation' knows how to extract it.
+
+ * The documentation for a variable is stored in the variable's
+ property list under the property name `variable-documentation'.
+ The function `documentation-property' knows how to extract it.
+
+ To save space, the documentation for preloaded functions and
+variables (including primitive functions and autoloaded functions) is
+stored in the "internal doc file" `DOC'. The documentation for
+functions and variables loaded during the XEmacs session from
+byte-compiled files is stored in those very same byte-compiled files
+(*note Docs and Compilation::).
+
+ XEmacs does not keep documentation strings in memory unless
+necessary. Instead, XEmacs maintains, for preloaded symbols, an
+integer offset into the internal doc file, and for symbols loaded from
+byte-compiled files, a list containing the filename of the
+byte-compiled file and an integer offset, in place of the documentation
+string. The functions `documentation' and `documentation-property' use
+that information to read the documentation from the appropriate file;
+this is transparent to the user.
+
+ For information on the uses of documentation strings, see *Note
+Help: (xemacs)Help.
+
+ The `emacs/lib-src' directory contains two utilities that you can
+use to print nice-looking hardcopy for the file
+`emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.
+
+\1f
+File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
+
+Access to Documentation Strings
+===============================
+
+ - Function: documentation-property symbol property &optional verbatim
+ This function returns the documentation string that is recorded in
+ SYMBOL's property list under property PROPERTY. It retrieves the
+ text from a file if necessary, and runs `substitute-command-keys'
+ to substitute actual key bindings. (This substitution is not done
+ if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
+ Emacs 19.)
+
+ (documentation-property 'command-line-processed
+ 'variable-documentation)
+ => "t once command line has been processed"
+ (symbol-plist 'command-line-processed)
+ => (variable-documentation 188902)
+
+ - Function: documentation function &optional verbatim
+ This function returns the documentation string of FUNCTION. It
+ reads the text from a file if necessary. Then (unless VERBATIM is
+ non-`nil') it calls `substitute-command-keys', to return a value
+ containing the actual (current) key bindings.
+
+ The function `documentation' signals a `void-function' error if
+ FUNCTION has no function definition. However, it is ok if the
+ function definition has no documentation string. In that case,
+ `documentation' returns `nil'.
+
+ Here is an example of using the two functions, `documentation' and
+`documentation-property', to display the documentation strings for
+several symbols in a `*Help*' buffer.
+
+ (defun describe-symbols (pattern)
+ "Describe the XEmacs Lisp symbols matching PATTERN.
+ All symbols that have PATTERN in their name are described
+ in the `*Help*' buffer."
+ (interactive "sDescribe symbols matching: ")
+ (let ((describe-func
+ (function
+ (lambda (s)
+ ;; Print description of symbol.
+ (if (fboundp s) ; It is a function.
+ (princ
+ (format "%s\t%s\n%s\n\n" s
+ (if (commandp s)
+ (let ((keys (where-is-internal s)))
+ (if keys
+ (concat
+ "Keys: "
+ (mapconcat 'key-description
+ keys " "))
+ "Keys: none"))
+ "Function")
+ (or (documentation s)
+ "not documented"))))
+
+ (if (boundp s) ; It is a variable.
+ (princ
+ (format "%s\t%s\n%s\n\n" s
+ (if (user-variable-p s)
+ "Option " "Variable")
+ (or (documentation-property
+ s 'variable-documentation)
+ "not documented")))))))
+ sym-list)
+
+ ;; Build a list of symbols that match pattern.
+ (mapatoms (function
+ (lambda (sym)
+ (if (string-match pattern (symbol-name sym))
+ (setq sym-list (cons sym sym-list))))))
+
+ ;; Display the data.
+ (with-output-to-temp-buffer "*Help*"
+ (mapcar describe-func (sort sym-list 'string<))
+ (print-help-return-message))))
+
+ The `describe-symbols' function works like `apropos', but provides
+more information.
+
+ (describe-symbols "goal")
+
+ ---------- Buffer: *Help* ----------
+ goal-column Option
+ *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
+
+ set-goal-column Command: C-x C-n
+ Set the current horizontal position as a goal for C-n and C-p.
+ Those commands will move to this position in the line moved to
+ rather than trying to keep the same horizontal position.
+ With a non-`nil' argument, clears out the goal column
+ so that C-n and C-p resume vertical motion.
+ The goal column is stored in the variable `goal-column'.
+
+ temporary-goal-column Variable
+ Current goal column for vertical motion.
+ It is the column where point was
+ at the start of current run of vertical motion commands.
+ When the `track-eol' feature is doing its job, the value is 9999.
+ ---------- Buffer: *Help* ----------
+
+ - Function: Snarf-documentation filename
+ This function is used only during XEmacs initialization, just
+ before the runnable XEmacs is dumped. It finds the file offsets
+ of the documentation strings stored in the file FILENAME, and
+ records them in the in-core function definitions and variable
+ property lists in place of the actual strings. *Note Building
+ XEmacs::.
+
+ XEmacs finds the file FILENAME in the `lib-src' directory. When
+ the dumped XEmacs is later executed, the same file is found in the
+ directory `doc-directory'. The usual value for FILENAME is `DOC',
+ but this can be changed by modifying the variable
+ `internal-doc-file-name'.
+
+ - Variable: internal-doc-file-name
+ This variable holds the name of the file containing documentation
+ strings of built-in symbols, usually `DOC'. The full pathname of
+ the internal doc file is `(concat doc-directory
+ internal-doc-file-name)'.
+
+ - Variable: doc-directory
+ This variable holds the name of the directory which contains the
+ "internal doc file" that contains documentation strings for
+ built-in and preloaded functions and variables.
+
+ In most cases, this is the same as `exec-directory'. They may be
+ different when you run XEmacs from the directory where you built
+ it, without actually installing it. See `exec-directory' in *Note
+ Help Functions::.
+
+ In older Emacs versions, `exec-directory' was used for this.
+
+ - Variable: data-directory
+ This variable holds the name of the directory in which XEmacs finds
+ certain system independent documentation and text files that come
+ with XEmacs. In older Emacs versions, `exec-directory' was used
+ for this.
+
+\1f
File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
Substituting Key Bindings in Documentation
*Please note:* Each `\' must be doubled when written in a string in
XEmacs Lisp.
- - Function: substitute-command-keys STRING
+ - Function: substitute-command-keys string
This function scans STRING for the above special sequences and
replaces them by what they stand for, returning the result as a
string. This permits display of documentation that refers
(substitute-command-keys
"To abort recursive edit, type: \\[abort-recursive-edit]")
=> "To abort recursive edit, type: C-]"
-
+
(substitute-command-keys
"The keys that are defined for the minibuffer here are:
\\{minibuffer-local-must-match-map}")
RET minibuffer-complete-and-exit
C-g abort-recursive-edit
"
+
(substitute-command-keys
"To abort a recursive edit from the minibuffer, type\
\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
=> "To abort a recursive edit from the minibuffer, type C-g."
-
+
(substitute-command-keys
"Substrings of the form \\=\\{MAPVAR} are replaced by summaries
- \(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
+ \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
as the keymap for future \\=\\[COMMAND] substrings.
\\=\\= quotes the following character and is discarded;
thus, \\=\\=\\=\\= puts \\=\\= into the output,
and \\=\\=\\=\\[ puts \\=\\[ into the output.")
=> "Substrings of the form \{MAPVAR} are replaced by summaries
- (made by describe-bindings) of the value of MAPVAR, taken as a keymap.
+ (made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
as the keymap for future \[COMMAND] substrings.
\= quotes the following character and is discarded;
characters. The description of a non-whitespace printing character is
the character itself.
- - Function: key-description SEQUENCE
+ - Function: key-description sequence
This function returns a string containing the XEmacs standard
notation for the input events in SEQUENCE. The argument SEQUENCE
may be a string, vector or list. *Note Events::, for more
information about valid events. See also the examples for
`single-key-description', below.
- - Function: single-key-description KEY
+ - Function: single-key-description key
This function returns a string describing KEY in the standard
XEmacs notation for keyboard input. A normal printing character
appears as itself, but a control character turns into a string
(single-key-description ?\C-x)
=> "C-x"
-
(key-description "\C-x \M-y \n \t \r \f123")
=> "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
-
(single-key-description 'kp_next)
=> "kp_next"
-
(single-key-description '(shift button1))
=> "Sh-button1"
- - Function: text-char-description CHARACTER
+ - Function: text-char-description character
This function returns a string describing CHARACTER in the
standard XEmacs notation for characters that appear in text--like
`single-key-description', except that control characters are
(text-char-description ?\C-c)
=> "^C"
-
(text-char-description ?\M-m)
=> "M-m"
-
(text-char-description ?\C-\M-m)
=> "M-^M"
-\1f
-File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
-
-Help Functions
-==============
-
- XEmacs provides a variety of on-line help functions, all accessible
-to the user as subcommands of the prefix `C-h', or on some keyboards,
-`help'. For more information about them, see *Note Help: (emacs)Help.
-Here we describe some program-level interfaces to the same information.
-
- - Command: apropos REGEXP &optional DO-ALL PREDICATE
- This function finds all symbols whose names contain a match for the
- regular expression REGEXP, and returns a list of them (*note
- Regular Expressions::.). It also displays the symbols in a buffer
- named `*Help*', each with a one-line description.
-
- If DO-ALL is non-`nil', then `apropos' also shows key bindings for
- the functions that are found.
-
- If PREDICATE is non-`nil', it should be a function to be called on
- each symbol that has matched REGEXP. Only symbols for which
- PREDICATE returns a non-`nil' value are listed or displayed.
-
- In the first of the following examples, `apropos' finds all the
- symbols with names containing `exec'. In the second example, it
- finds and returns only those symbols that are also commands. (We
- don't show the output that results in the `*Help*' buffer.)
-
- (apropos "exec")
- => (Buffer-menu-execute command-execute exec-directory
- exec-path execute-extended-command execute-kbd-macro
- executing-kbd-macro executing-macro)
-
- (apropos "exec" nil 'commandp)
- => (Buffer-menu-execute execute-extended-command)
-
- `apropos' is used by various user-level commands, such as `C-h a'
- (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
- (`command-apropos'), which does an apropos over only those
- functions which are user commands. `command-apropos' calls
- `apropos', specifying a PREDICATE to restrict the output to
- symbols that are commands. The call to `apropos' looks like this:
-
- (apropos string t 'commandp)
-
- - Variable: help-map
- The value of this variable is a local keymap for characters
- following the Help key, `C-h'.
-
- - Prefix Command: help-command
- This symbol is not a function; its function definition is actually
- the keymap known as `help-map'. It is defined in `help.el' as
- follows:
-
- (define-key global-map "\C-h" 'help-command)
- (fset 'help-command help-map)
-
- - Function: print-help-return-message &optional FUNCTION
- This function builds a string that explains how to restore the
- previous state of the windows after a help command. After
- building the message, it applies FUNCTION to it if FUNCTION is
- non-`nil'. Otherwise it calls `message' to display it in the echo
- area.
-
- This function expects to be called inside a
- `with-output-to-temp-buffer' special form, and expects
- `standard-output' to have the value bound by that special form.
- For an example of its use, see the long example in *Note Accessing
- Documentation::.
-
- - Variable: help-char
- The value of this variable is the help character--the character
- that XEmacs recognizes as meaning Help. By default, it is the
- character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
- character, if `help-form' is non-`nil' Lisp expression, it
- evaluates that expression, and displays the result in a window if
- it is a string.
-
- `help-char' can be a character or a key description such as `help'
- or `(meta h)'.
-
- Usually the value of `help-form''s value is `nil'. Then the help
- character has no special meaning at the level of command input, and
- it becomes part of a key sequence in the normal way. The standard
- key binding of `C-h' is a prefix key for several general-purpose
- help features.
-
- The help character is special after prefix keys, too. If it has no
- binding as a subcommand of the prefix key, it runs
- `describe-prefix-bindings', which displays a list of all the
- subcommands of the prefix key.
-
- - Variable: help-form
- If this variable is non-`nil', its value is a form to evaluate
- whenever the character `help-char' is read. If evaluating the form
- produces a string, that string is displayed.
-
- A command that calls `next-command-event' or `next-event' probably
- should bind `help-form' to a non-`nil' expression while it does
- input. (The exception is when `C-h' is meaningful input.)
- Evaluating this expression should result in a string that explains
- what the input is for and how to enter it properly.
-
- Entry to the minibuffer binds this variable to the value of
- `minibuffer-help-form' (*note Minibuffer Misc::.).
-
- - Variable: prefix-help-command
- This variable holds a function to print help for a prefix
- character. The function is called when the user types a prefix
- key followed by the help character, and the help character has no
- binding after that prefix. The variable's default value is
- `describe-prefix-bindings'.
-
- - Function: describe-prefix-bindings
- This function calls `describe-bindings' to display a list of all
- the subcommands of the prefix key of the most recent key sequence.
- The prefix described consists of all but the last event of that
- key sequence. (The last event is, presumably, the help character.)
-
- The following two functions are found in the library `helper'. They
-are for modes that want to provide help without relinquishing control,
-such as the "electric" modes. You must load that library with
-`(require 'helper)' in order to use them. Their names begin with
-`Helper' to distinguish them from the ordinary help functions.
-
- - Command: Helper-describe-bindings
- This command pops up a window displaying a help buffer containing a
- listing of all of the key bindings from both the local and global
- keymaps. It works by calling `describe-bindings'.
-
- - Command: Helper-help
- This command provides help for the current mode. It prompts the
- user in the minibuffer with the message `Help (Type ? for further
- options)', and then provides assistance in finding out what the key
- bindings are, and what the mode is intended for. It returns `nil'.
-
- This can be customized by changing the map `Helper-help-map'.
-
-\1f
-File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
-
-Obsoleteness
-============
-
- As you add functionality to a package, you may at times want to
-replace an older function with a new one. To preserve compatibility
-with existing code, the older function needs to still exist; but users
-of that function should be told to use the newer one instead. XEmacs
-Lisp lets you mark a function or variable as "obsolete", and indicate
-what should be used instead.
-
- - Function: make-obsolete FUNCTION NEW
- This function indicates that FUNCTION is an obsolete function, and
- the function NEW should be used instead. The byte compiler will
- issue a warning to this effect when it encounters a usage of the
- older function, and the help system will also note this in the
- function's documentation. NEW can also be a string (if there is
- not a single function with the same functionality any more), and
- should be a descriptive statement, such as "use FOO or BAR
- instead" or "this function is unnecessary".
-
- - Function: make-obsolete-variable VARIABLE NEW
- This is like `make-obsolete' but is for variables instead of
- functions.
-
- - Function: define-obsolete-function-alias OLDFUN NEWFUN
- This function combines `make-obsolete' and `define-function',
- declaring OLDFUN to be an obsolete variant of NEWFUN and defining
- OLDFUN as an alias for NEWFUN.
-
- - Function: define-obsolete-variable-alias OLDVAR NEWVAR
- This is like `define-obsolete-function-alias' but for variables.
-
- Note that you should not normally put obsoleteness information
-explicitly in a function or variable's doc string. The obsoleteness
-information that you specify using the above functions will be displayed
-whenever the doc string is displayed, and by adding it explicitly the
-result is redundancy.
-
- Also, if an obsolete function is substantially the same as a newer
-one but is not actually an alias, you should consider omitting the doc
-string entirely (use a null string `""' as the doc string). That way,
-the user is told about the obsoleteness and is forced to look at the
-documentation of the new function, making it more likely that he will
-use the new function.
-
- - Function: function-obsoleteness-doc FUNCTION
- If FUNCTION is obsolete, this function returns a string describing
- this. This is the message that is printed out during byte
- compilation or in the function's documentation. If FUNCTION is
- not obsolete, `nil' is returned.
-
- - Function: variable-obsoleteness-doc VARIABLE
- This is like `function-obsoleteness-doc' but for variables.
-
- The obsoleteness information is stored internally by putting a
-property `byte-obsolete-info' (for functions) or
-`byte-obsolete-variable' (for variables) on the symbol that specifies
-the obsolete function or variable. For more information, see the
-implementation of `make-obsolete' and `make-obsolete-variable' in
-`lisp/bytecomp/bytecomp-runtime.el'.
-
-\1f
-File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
-
-Files
-*****
-
- In XEmacs, you can find, create, view, save, and otherwise work with
-files and file directories. This chapter describes most of the
-file-related functions of XEmacs Lisp, but a few others are described in
-*Note Buffers::, and those related to backups and auto-saving are
-described in *Note Backups and Auto-Saving::.
-
- Many of the file functions take one or more arguments that are file
-names. A file name is actually a string. Most of these functions
-expand file name arguments using `expand-file-name', so that `~' is
-handled correctly, as are relative file names (including `../'). These
-functions don't recognize environment variable substitutions such as
-`$HOME'. *Note File Name Expansion::.
-
-* Menu:
-
-* Visiting Files:: Reading files into Emacs buffers for editing.
-* Saving Buffers:: Writing changed buffers back into files.
-* Reading from Files:: Reading files into buffers without visiting.
-* Writing to Files:: Writing new files from parts of buffers.
-* File Locks:: Locking and unlocking files, to prevent
- simultaneous editing by two people.
-* Information about Files:: Testing existence, accessibility, size of files.
-* Changing File Attributes:: Renaming files, changing protection, etc.
-* File Names:: Decomposing and expanding file names.
-* Contents of Directories:: Getting a list of the files in a directory.
-* Create/Delete Dirs:: Creating and Deleting Directories.
-* Magic File Names:: Defining "magic" special handling
- for certain file names.
-* Partial Files:: Treating a section of a buffer as a file.
-* Format Conversion:: Conversion to and from various file formats.
-* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
-
-\1f
-File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
-
-Visiting Files
-==============
-
- Visiting a file means reading a file into a buffer. Once this is
-done, we say that the buffer is "visiting" that file, and call the file
-"the visited file" of the buffer.
-
- A file and a buffer are two different things. A file is information
-recorded permanently in the computer (unless you delete it). A buffer,
-on the other hand, is information inside of XEmacs that will vanish at
-the end of the editing session (or when you kill the buffer). Usually,
-a buffer contains information that you have copied from a file; then we
-say the buffer is visiting that file. The copy in the buffer is what
-you modify with editing commands. Such changes to the buffer do not
-change the file; therefore, to make the changes permanent, you must
-"save" the buffer, which means copying the altered buffer contents back
-into the file.
-
- In spite of the distinction between files and buffers, people often
-refer to a file when they mean a buffer and vice-versa. Indeed, we say,
-"I am editing a file," rather than, "I am editing a buffer that I will
-soon save as a file of the same name." Humans do not usually need to
-make the distinction explicit. When dealing with a computer program,
-however, it is good to keep the distinction in mind.
-
-* Menu:
-
-* Visiting Functions:: The usual interface functions for visiting.
-* Subroutines of Visiting:: Lower-level subroutines that they use.
-
-\1f
-File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
-
-Functions for Visiting Files
-----------------------------
-
- This section describes the functions normally used to visit files.
-For historical reasons, these functions have names starting with
-`find-' rather than `visit-'. *Note Buffer File Name::, for functions
-and variables that access the visited file name of a buffer or that
-find an existing buffer by its visited file name.
-
- In a Lisp program, if you want to look at the contents of a file but
-not alter it, the fastest way is to use `insert-file-contents' in a
-temporary buffer. Visiting the file is not necessary and takes longer.
-*Note Reading from Files::.
-
- - Command: find-file FILENAME
- This command selects a buffer visiting the file FILENAME, using an
- existing buffer if there is one, and otherwise creating a new
- buffer and reading the file into it. It also returns that buffer.
-
- The body of the `find-file' function is very simple and looks like
- this:
-
- (switch-to-buffer (find-file-noselect filename))
-
- (See `switch-to-buffer' in *Note Displaying Buffers::.)
-
- When `find-file' is called interactively, it prompts for FILENAME
- in the minibuffer.
-
- - Function: find-file-noselect FILENAME &optional NOWARN
- This function is the guts of all the file-visiting functions. It
- finds or creates a buffer visiting the file FILENAME, and returns
- it. It uses an existing buffer if there is one, and otherwise
- creates a new buffer and reads the file into it. You may make the
- buffer current or display it in a window if you wish, but this
- function does not do so.
-
- When `find-file-noselect' uses an existing buffer, it first
- verifies that the file has not changed since it was last visited or
- saved in that buffer. If the file has changed, then this function
- asks the user whether to reread the changed file. If the user says
- `yes', any changes previously made in the buffer are lost.
-
- If `find-file-noselect' needs to create a buffer, and there is no
- file named FILENAME, it displays the message `New file' in the
- echo area, and leaves the buffer empty.
-
- If NO-WARN is non-`nil', various warnings that XEmacs normally
- gives (e.g. if another buffer is already visiting FILENAME but
- FILENAME has been removed from disk since that buffer was created)
- are suppressed.
-
- The `find-file-noselect' function calls `after-find-file' after
- reading the file (*note Subroutines of Visiting::.). That function
- sets the buffer major mode, parses local variables, warns the user
- if there exists an auto-save file more recent than the file just
- visited, and finishes by running the functions in
- `find-file-hooks'.
-
- The `find-file-noselect' function returns the buffer that is
- visiting the file FILENAME.
-
- (find-file-noselect "/etc/fstab")
- => #<buffer fstab>
-
- - Command: find-file-other-window FILENAME
- This command selects a buffer visiting the file FILENAME, but does
- so in a window other than the selected window. It may use another
- existing window or split a window; see *Note Displaying Buffers::.
-
- When this command is called interactively, it prompts for FILENAME.
-
- - Command: find-file-read-only FILENAME
- This command selects a buffer visiting the file FILENAME, like
- `find-file', but it marks the buffer as read-only. *Note Read
- Only Buffers::, for related functions and variables.
-
- When this command is called interactively, it prompts for FILENAME.
-
- - Command: view-file FILENAME
- This command visits FILENAME in View mode, and displays it in a
- recursive edit, returning to the previous buffer when done. View
- mode is a mode that allows you to skim rapidly through the file
- but does not let you modify it. Entering View mode runs the
- normal hook `view-mode-hook'. *Note Hooks::.
-
- When `view-file' is called interactively, it prompts for FILENAME.
-
- - Variable: find-file-hooks
- The value of this variable is a list of functions to be called
- after a file is visited. The file's local-variables specification
- (if any) will have been processed before the hooks are run. The
- buffer visiting the file is current when the hook functions are
- run.
-
- This variable works just like a normal hook, but we think that
- renaming it would not be advisable.
-
- - Variable: find-file-not-found-hooks
- The value of this variable is a list of functions to be called when
- `find-file' or `find-file-noselect' is passed a nonexistent file
- name. `find-file-noselect' calls these functions as soon as it
- detects a nonexistent file. It calls them in the order of the
- list, until one of them returns non-`nil'. `buffer-file-name' is
- already set up.
-
- This is not a normal hook because the values of the functions are
- used and they may not all be called.
-
-\1f
-File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
-
-Subroutines of Visiting
------------------------
-
- The `find-file-noselect' function uses the `create-file-buffer' and
-`after-find-file' functions as subroutines. Sometimes it is useful to
-call them directly.
-
- - Function: create-file-buffer FILENAME
- This function creates a suitably named buffer for visiting
- FILENAME, and returns it. It uses FILENAME (sans directory) as
- the name if that name is free; otherwise, it appends a string such
- as `<2>' to get an unused name. See also *Note Creating Buffers::.
-
- *Please note:* `create-file-buffer' does *not* associate the new
- buffer with a file and does not select the buffer. It also does
- not use the default major mode.
-
- (create-file-buffer "foo")
- => #<buffer foo>
- (create-file-buffer "foo")
- => #<buffer foo<2>>
- (create-file-buffer "foo")
- => #<buffer foo<3>>
-
- This function is used by `find-file-noselect'. It uses
- `generate-new-buffer' (*note Creating Buffers::.).
-
- - Function: after-find-file &optional ERROR WARN NOAUTO
- This function sets the buffer major mode, and parses local
- variables (*note Auto Major Mode::.). It is called by
- `find-file-noselect' and by the default revert function (*note
- Reverting::.).
-
- If reading the file got an error because the file does not exist,
- but its directory does exist, the caller should pass a non-`nil'
- value for ERROR. In that case, `after-find-file' issues a warning:
- `(New File)'. For more serious errors, the caller should usually
- not call `after-find-file'.
-
- If WARN is non-`nil', then this function issues a warning if an
- auto-save file exists and is more recent than the visited file.
-
- If NOAUTO is non-`nil', then this function does not turn on
- auto-save mode; otherwise, it does.
-
- The last thing `after-find-file' does is call all the functions in
- `find-file-hooks'.
-
-\1f
-File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
-
-Saving Buffers
-==============
-
- When you edit a file in XEmacs, you are actually working on a buffer
-that is visiting that file--that is, the contents of the file are
-copied into the buffer and the copy is what you edit. Changes to the
-buffer do not change the file until you "save" the buffer, which means
-copying the contents of the buffer into the file.
-
- - Command: save-buffer &optional BACKUP-OPTION
- This function saves the contents of the current buffer in its
- visited file if the buffer has been modified since it was last
- visited or saved. Otherwise it does nothing.
-
- `save-buffer' is responsible for making backup files. Normally,
- BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
- if this is the first save since visiting the file. Other values
- for BACKUP-OPTION request the making of backup files in other
- circumstances:
-
- * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
- `save-buffer' function marks this version of the file to be
- backed up when the buffer is next saved.
-
- * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
- `save-buffer' function unconditionally backs up the previous
- version of the file before saving it.
-
- - Command: save-some-buffers &optional SAVE-SILENTLY-P EXITING
- This command saves some modified file-visiting buffers. Normally
- it asks the user about each buffer. But if SAVE-SILENTLY-P is
- non-`nil', it saves all the file-visiting buffers without querying
- the user.
-
- The optional EXITING argument, if non-`nil', requests this
- function to offer also to save certain other buffers that are not
- visiting files. These are buffers that have a non-`nil' local
- value of `buffer-offer-save'. (A user who says yes to saving one
- of these is asked to specify a file name to use.) The
- `save-buffers-kill-emacs' function passes a non-`nil' value for
- this argument.
-
- - Variable: buffer-offer-save
- When this variable is non-`nil' in a buffer, XEmacs offers to save
- the buffer on exit even if the buffer is not visiting a file. The
- variable is automatically local in all buffers. Normally, Mail
- mode (used for editing outgoing mail) sets this to `t'.
-
- - Command: write-file FILENAME
- This function writes the current buffer into file FILENAME, makes
- the buffer visit that file, and marks it not modified. Then it
- renames the buffer based on FILENAME, appending a string like `<2>'
- if necessary to make a unique buffer name. It does most of this
- work by calling `set-visited-file-name' and `save-buffer'.
-
- - Variable: write-file-hooks
- The value of this variable is a list of functions to be called
- before writing out a buffer to its visited file. If one of them
- returns non-`nil', the file is considered already written and the
- rest of the functions are not called, nor is the usual code for
- writing the file executed.
-
- If a function in `write-file-hooks' returns non-`nil', it is
- responsible for making a backup file (if that is appropriate). To
- do so, execute the following code:
-
- (or buffer-backed-up (backup-buffer))
-
- You might wish to save the file modes value returned by
- `backup-buffer' and use that to set the mode bits of the file that
- you write. This is what `save-buffer' normally does.
-
- Even though this is not a normal hook, you can use `add-hook' and
- `remove-hook' to manipulate the list. *Note Hooks::.
-
- - Variable: local-write-file-hooks
- This works just like `write-file-hooks', but it is intended to be
- made local to particular buffers. It's not a good idea to make
- `write-file-hooks' local to a buffer--use this variable instead.
-
- The variable is marked as a permanent local, so that changing the
- major mode does not alter a buffer-local value. This is
- convenient for packages that read "file" contents in special ways,
- and set up hooks to save the data in a corresponding way.
-
- - Variable: write-contents-hooks
- This works just like `write-file-hooks', but it is intended for
- hooks that pertain to the contents of the file, as opposed to
- hooks that pertain to where the file came from. Such hooks are
- usually set up by major modes, as buffer-local bindings for this
- variable. Switching to a new major mode always resets this
- variable.
-
- - Variable: after-save-hook
- This normal hook runs after a buffer has been saved in its visited
- file.
-
- - Variable: file-precious-flag
- If this variable is non-`nil', then `save-buffer' protects against
- I/O errors while saving by writing the new file to a temporary
- name instead of the name it is supposed to have, and then renaming
- it to the intended name after it is clear there are no errors.
- This procedure prevents problems such as a lack of disk space from
- resulting in an invalid file.
-
- As a side effect, backups are necessarily made by copying. *Note
- Rename or Copy::. Yet, at the same time, saving a precious file
- always breaks all hard links between the file you save and other
- file names.
-
- Some modes set this variable non-`nil' locally in particular
- buffers.
-
- - User Option: require-final-newline
- This variable determines whether files may be written out that do
- *not* end with a newline. If the value of the variable is `t',
- then `save-buffer' silently adds a newline at the end of the file
- whenever the buffer being saved does not already end in one. If
- the value of the variable is non-`nil', but not `t', then
- `save-buffer' asks the user whether to add a newline each time the
- case arises.
-
- If the value of the variable is `nil', then `save-buffer' doesn't
- add newlines at all. `nil' is the default value, but a few major
- modes set it to `t' in particular buffers.
-
-\1f
-File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
-
-Reading from Files
-==================
-
- You can copy a file from the disk and insert it into a buffer using
-the `insert-file-contents' function. Don't use the user-level command
-`insert-file' in a Lisp program, as that sets the mark.
-
- - Function: insert-file-contents FILENAME &optional VISIT BEG END
- REPLACE
- This function inserts the contents of file FILENAME into the
- current buffer after point. It returns a list of the absolute
- file name and the length of the data inserted. An error is
- signaled if FILENAME is not the name of a file that can be read.
-
- The function `insert-file-contents' checks the file contents
- against the defined file formats, and converts the file contents if
- appropriate. *Note Format Conversion::. It also calls the
- functions in the list `after-insert-file-functions'; see *Note
- Saving Properties::.
-
- If VISIT is non-`nil', this function additionally marks the buffer
- as unmodified and sets up various fields in the buffer so that it
- is visiting the file FILENAME: these include the buffer's visited
- file name and its last save file modtime. This feature is used by
- `find-file-noselect' and you probably should not use it yourself.
-
- If BEG and END are non-`nil', they should be integers specifying
- the portion of the file to insert. In this case, VISIT must be
- `nil'. For example,
-
- (insert-file-contents filename nil 0 500)
-
- inserts the first 500 characters of a file.
-
- If the argument REPLACE is non-`nil', it means to replace the
- contents of the buffer (actually, just the accessible portion)
- with the contents of the file. This is better than simply
- deleting the buffer contents and inserting the whole file, because
- (1) it preserves some marker positions and (2) it puts less data
- in the undo list.
-
- If you want to pass a file name to another process so that another
-program can read the file, use the function `file-local-copy'; see
-*Note Magic File Names::.
-
-\1f
-File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
-
-Writing to Files
-================
-
- You can write the contents of a buffer, or part of a buffer, directly
-to a file on disk using the `append-to-file' and `write-region'
-functions. Don't use these functions to write to files that are being
-visited; that could cause confusion in the mechanisms for visiting.
-
- - Command: append-to-file START END FILENAME
- This function appends the contents of the region delimited by
- START and END in the current buffer to the end of file FILENAME.
- If that file does not exist, it is created. If that file exists
- it is overwritten. This function returns `nil'.
-
- An error is signaled if FILENAME specifies a nonwritable file, or
- a nonexistent file in a directory where files cannot be created.
-
- - Command: write-region START END FILENAME &optional APPEND VISIT
- This function writes the region delimited by START and END in the
- current buffer into the file specified by FILENAME.
-
- If START is a string, then `write-region' writes or appends that
- string, rather than text from the buffer.
-
- If APPEND is non-`nil', then the specified text is appended to the
- existing file contents (if any).
-
- If VISIT is `t', then XEmacs establishes an association between
- the buffer and the file: the buffer is then visiting that file.
- It also sets the last file modification time for the current
- buffer to FILENAME's modtime, and marks the buffer as not
- modified. This feature is used by `save-buffer', but you probably
- should not use it yourself.
-
- If VISIT is a string, it specifies the file name to visit. This
- way, you can write the data to one file (FILENAME) while recording
- the buffer as visiting another file (VISIT). The argument VISIT
- is used in the echo area message and also for file locking; VISIT
- is stored in `buffer-file-name'. This feature is used to
- implement `file-precious-flag'; don't use it yourself unless you
- really know what you're doing.
-
- The function `write-region' converts the data which it writes to
- the appropriate file formats specified by `buffer-file-format'.
- *Note Format Conversion::. It also calls the functions in the list
- `write-region-annotate-functions'; see *Note Saving Properties::.
-
- Normally, `write-region' displays a message `Wrote file FILENAME'
- in the echo area. If VISIT is neither `t' nor `nil' nor a string,
- then this message is inhibited. This feature is useful for
- programs that use files for internal purposes, files that the user
- does not need to know about.
-
-\1f
-File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
-
-File Locks
-==========
-
- When two users edit the same file at the same time, they are likely
-to interfere with each other. XEmacs tries to prevent this situation
-from arising by recording a "file lock" when a file is being modified.
-XEmacs can then detect the first attempt to modify a buffer visiting a
-file that is locked by another XEmacs process, and ask the user what to
-do.
-
- File locks do not work properly when multiple machines can share
-file systems, such as with NFS. Perhaps a better file locking system
-will be implemented in the future. When file locks do not work, it is
-possible for two users to make changes simultaneously, but XEmacs can
-still warn the user who saves second. Also, the detection of
-modification of a buffer visiting a file changed on disk catches some
-cases of simultaneous editing; see *Note Modification Time::.
-
- - Function: file-locked-p &optional FILENAME
- This function returns `nil' if the file FILENAME is not locked by
- this XEmacs process. It returns `t' if it is locked by this
- XEmacs, and it returns the name of the user who has locked it if it
- is locked by someone else.
-
- (file-locked-p "foo")
- => nil
-
- - Function: lock-buffer &optional FILENAME
- This function locks the file FILENAME, if the current buffer is
- modified. The argument FILENAME defaults to the current buffer's
- visited file. Nothing is done if the current buffer is not
- visiting a file, or is not modified.
-
- - Function: unlock-buffer
- This function unlocks the file being visited in the current buffer,
- if the buffer is modified. If the buffer is not modified, then
- the file should not be locked, so this function does nothing. It
- also does nothing if the current buffer is not visiting a file.
-
- - Function: ask-user-about-lock FILE OTHER-USER
- This function is called when the user tries to modify FILE, but it
- is locked by another user named OTHER-USER. The value it returns
- determines what happens next:
-
- * A value of `t' says to grab the lock on the file. Then this
- user may edit the file and OTHER-USER loses the lock.
-
- * A value of `nil' says to ignore the lock and let this user
- edit the file anyway.
-
- * This function may instead signal a `file-locked' error, in
- which case the change that the user was about to make does
- not take place.
-
- The error message for this error looks like this:
-
- error--> File is locked: FILE OTHER-USER
-
- where `file' is the name of the file and OTHER-USER is the
- name of the user who has locked the file.
-
- The default definition of this function asks the user to choose
- what to do. If you wish, you can replace the `ask-user-about-lock'
- function with your own version that decides in another way. The
- code for its usual definition is in `userlock.el'.
-
-\1f
-File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
-
-Information about Files
-=======================
-
- The functions described in this section all operate on strings that
-designate file names. All the functions have names that begin with the
-word `file'. These functions all return information about actual files
-or directories, so their arguments must all exist as actual files or
-directories unless otherwise noted.
-
-* Menu:
-
-* Testing Accessibility:: Is a given file readable? Writable?
-* Kinds of Files:: Is it a directory? A symbolic link?
-* Truenames:: Eliminating symbolic links from a file name.
-* File Attributes:: How large is it? Any other names? Etc.
-
-\1f
-File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
-
-Testing Accessibility
----------------------
-
- These functions test for permission to access a file in specific
-ways.
-
- - Function: file-exists-p FILENAME
- This function returns `t' if a file named FILENAME appears to
- exist. This does not mean you can necessarily read the file, only
- that you can find out its attributes. (On Unix, this is true if
- the file exists and you have execute permission on the containing
- directories, regardless of the protection of the file itself.)
-
- If the file does not exist, or if fascist access control policies
- prevent you from finding the attributes of the file, this function
- returns `nil'.
-
- - Function: file-readable-p FILENAME
- This function returns `t' if a file named FILENAME exists and you
- can read it. It returns `nil' otherwise.
-
- (file-readable-p "files.texi")
- => t
- (file-exists-p "/usr/spool/mqueue")
- => t
- (file-readable-p "/usr/spool/mqueue")
- => nil
-
- - Function: file-executable-p FILENAME
- This function returns `t' if a file named FILENAME exists and you
- can execute it. It returns `nil' otherwise. If the file is a
- directory, execute permission means you can check the existence and
- attributes of files inside the directory, and open those files if
- their modes permit.
-
- - Function: file-writable-p FILENAME
- This function returns `t' if the file FILENAME can be written or
- created by you, and `nil' otherwise. A file is writable if the
- file exists and you can write it. It is creatable if it does not
- exist, but the specified directory does exist and you can write in
- that directory.
-
- In the third example below, `foo' is not writable because the
- parent directory does not exist, even though the user could create
- such a directory.
-
- (file-writable-p "~/foo")
- => t
- (file-writable-p "/foo")
- => nil
- (file-writable-p "~/no-such-dir/foo")
- => nil
-
- - Function: file-accessible-directory-p DIRNAME
- This function returns `t' if you have permission to open existing
- files in the directory whose name as a file is DIRNAME; otherwise
- (or if there is no such directory), it returns `nil'. The value
- of DIRNAME may be either a directory name or the file name of a
- directory.
-
- Example: after the following,
-
- (file-accessible-directory-p "/foo")
- => nil
-
- we can deduce that any attempt to read a file in `/foo/' will give
- an error.
-
- - Function: file-ownership-preserved-p FILENAME
- This function returns `t' if deleting the file FILENAME and then
- creating it anew would keep the file's owner unchanged.
-
- - Function: file-newer-than-file-p FILENAME1 FILENAME2
- This function returns `t' if the file FILENAME1 is newer than file
- FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
- FILENAME2 does not exist, it returns `t'.
-
- In the following example, assume that the file `aug-19' was written
- on the 19th, `aug-20' was written on the 20th, and the file
- `no-file' doesn't exist at all.
-
- (file-newer-than-file-p "aug-19" "aug-20")
- => nil
- (file-newer-than-file-p "aug-20" "aug-19")
- => t
- (file-newer-than-file-p "aug-19" "no-file")
- => t
- (file-newer-than-file-p "no-file" "aug-19")
- => nil
-
- You can use `file-attributes' to get a file's last modification
- time as a list of two numbers. *Note File Attributes::.
-
-\1f
-File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
-
-Distinguishing Kinds of Files
------------------------------
-
- This section describes how to distinguish various kinds of files,
-such as directories, symbolic links, and ordinary files.
-
- - Function: file-symlink-p FILENAME
- If the file FILENAME is a symbolic link, the `file-symlink-p'
- function returns the file name to which it is linked. This may be
- the name of a text file, a directory, or even another symbolic
- link, or it may be a nonexistent file name.
-
- If the file FILENAME is not a symbolic link (or there is no such
- file), `file-symlink-p' returns `nil'.
-
- (file-symlink-p "foo")
- => nil
- (file-symlink-p "sym-link")
- => "foo"
- (file-symlink-p "sym-link2")
- => "sym-link"
- (file-symlink-p "/bin")
- => "/pub/bin"
-
-
- - Function: file-directory-p FILENAME
- This function returns `t' if FILENAME is the name of an existing
- directory, `nil' otherwise.
-
- (file-directory-p "~rms")
- => t
- (file-directory-p "~rms/lewis/files.texi")
- => nil
- (file-directory-p "~rms/lewis/no-such-file")
- => nil
- (file-directory-p "$HOME")
- => nil
- (file-directory-p
- (substitute-in-file-name "$HOME"))
- => t
-
- - Function: file-regular-p FILENAME
- This function returns `t' if the file FILENAME exists and is a
- regular file (not a directory, symbolic link, named pipe,
- terminal, or other I/O device).
-
-\1f
-File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
-
-Truenames
----------
-
- The "truename" of a file is the name that you get by following
-symbolic links until none remain, then expanding to get rid of `.' and
-`..' as components. Strictly speaking, a file need not have a unique
-truename; the number of distinct truenames a file has is equal to the
-number of hard links to the file. However, truenames are useful
-because they eliminate symbolic links as a cause of name variation.
-
- - Function: file-truename FILENAME &optional DEFAULT
- The function `file-truename' returns the true name of the file
- FILENAME. This is the name that you get by following symbolic
- links until none remain.
-
- If the filename is relative, DEFAULT is the directory to start
- with. If DEFAULT is `nil' or missing, the current buffer's value
- of `default-directory' is used.
-
- *Note Buffer File Name::, for related information.
-
projects / chise / xemacs-chise.git- / blobdiff