+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes
-
-How XEmacs Chooses a Major Mode
--------------------------------
-
- Based on information in the file name or in the file itself, XEmacs
-automatically selects a major mode for the new buffer when a file is
-visited.
-
- - Command: fundamental-mode
- Fundamental mode is a major mode that is not specialized for
- anything in particular. Other major modes are defined in effect
- by comparison with this one--their definitions say what to change,
- starting from Fundamental mode. The `fundamental-mode' function
- does *not* run any hooks; you're not supposed to customize it.
- (If you want Emacs to behave differently in Fundamental mode,
- change the *global* state of Emacs.)
-
- - Command: normal-mode &optional FIND-FILE
- This function establishes the proper major mode and local variable
- bindings for the current buffer. First it calls `set-auto-mode',
- then it runs `hack-local-variables' to parse, and bind or evaluate
- as appropriate, any local variables.
-
- If the FIND-FILE argument to `normal-mode' is non-`nil',
- `normal-mode' assumes that the `find-file' function is calling it.
- In this case, it may process a local variables list at the end of
- the file and in the `-*-' line. The variable
- `enable-local-variables' controls whether to do so.
-
- If you run `normal-mode' interactively, the argument FIND-FILE is
- normally `nil'. In this case, `normal-mode' unconditionally
- processes any local variables list. *Note Local Variables in
- Files: (emacs)File variables, for the syntax of the local
- variables section of a file.
-
- `normal-mode' uses `condition-case' around the call to the major
- mode function, so errors are caught and reported as a `File mode
- specification error', followed by the original error message.
-
- - User Option: enable-local-variables
- This variable controls processing of local variables lists in files
- being visited. A value of `t' means process the local variables
- lists unconditionally; `nil' means ignore them; anything else means
- ask the user what to do for each file. The default value is `t'.
-
- - Variable: ignored-local-variables
- This variable holds a list of variables that should not be set by
- a local variables list. Any value specified for one of these
- variables is ignored.
-
- In addition to this list, any variable whose name has a non-`nil'
-`risky-local-variable' property is also ignored.
-
- - User Option: enable-local-eval
- This variable controls processing of `Eval:' in local variables
- lists in files being visited. A value of `t' means process them
- unconditionally; `nil' means ignore them; anything else means ask
- the user what to do for each file. The default value is `maybe'.
-
- - Function: set-auto-mode
- This function selects the major mode that is appropriate for the
- current buffer. It may base its decision on the value of the `-*-'
- line, on the visited file name (using `auto-mode-alist'), or on the
- value of a local variable. However, this function does not look
- for the `mode:' local variable near the end of a file; the
- `hack-local-variables' function does that. *Note How Major Modes
- are Chosen: (emacs)Choosing Modes.
-
- - User Option: default-major-mode
- This variable holds the default major mode for new buffers. The
- standard value is `fundamental-mode'.
-
- If the value of `default-major-mode' is `nil', XEmacs uses the
- (previously) current buffer's major mode for the major mode of a
- new buffer. However, if the major mode symbol has a `mode-class'
- property with value `special', then it is not used for new buffers;
- Fundamental mode is used instead. The modes that have this
- property are those such as Dired and Rmail that are useful only
- with text that has been specially prepared.
-
- - Function: set-buffer-major-mode BUFFER
- This function sets the major mode of BUFFER to the value of
- `default-major-mode'. If that variable is `nil', it uses the
- current buffer's major mode (if that is suitable).
-
- The low-level primitives for creating buffers do not use this
- function, but medium-level commands such as `switch-to-buffer' and
- `find-file-noselect' use it whenever they create buffers.
-
- - Variable: initial-major-mode
- The value of this variable determines the major mode of the initial
- `*scratch*' buffer. The value should be a symbol that is a major
- mode command name. The default value is `lisp-interaction-mode'.
-
- - Variable: auto-mode-alist
- This variable contains an association list of file name patterns
- (regular expressions; *note Regular Expressions::.) and
- corresponding major mode functions. Usually, the file name
- patterns test for suffixes, such as `.el' and `.c', but this need
- not be the case. An ordinary element of the alist looks like
- `(REGEXP . MODE-FUNCTION)'.
-
- For example,
-
- (("^/tmp/fol/" . text-mode)
- ("\\.texinfo\\'" . texinfo-mode)
- ("\\.texi\\'" . texinfo-mode)
-
- ("\\.el\\'" . emacs-lisp-mode)
- ("\\.c\\'" . c-mode)
- ("\\.h\\'" . c-mode)
- ...)
-
- When you visit a file whose expanded file name (*note File Name
- Expansion::.) matches a REGEXP, `set-auto-mode' calls the
- corresponding MODE-FUNCTION. This feature enables XEmacs to select
- the proper major mode for most files.
-
- If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
- t)', then after calling FUNCTION, XEmacs searches
- `auto-mode-alist' again for a match against the portion of the file
- name that did not match before.
-
- This match-again feature is useful for uncompression packages: an
- entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
- and then put the uncompressed file in the proper mode according to
- the name sans `.gz'.
-
- Here is an example of how to prepend several pattern pairs to
- `auto-mode-alist'. (You might use this sort of expression in your
- `.emacs' file.)
-
- (setq auto-mode-alist
- (append
- ;; File name starts with a dot.
- '(("/\\.[^/]*\\'" . fundamental-mode)
- ;; File name has no dot.
- ("[^\\./]*\\'" . fundamental-mode)
- ;; File name ends in `.C'.
- ("\\.C\\'" . c++-mode))
- auto-mode-alist))
-
- - Variable: interpreter-mode-alist
- This variable specifies major modes to use for scripts that
- specify a command interpreter in an `#!' line. Its value is a
- list of elements of the form `(INTERPRETER . MODE)'; for example,
- `("perl" . perl-mode)' is one element present by default. The
- element says to use mode MODE if the file specifies INTERPRETER.
-
- This variable is applicable only when the `auto-mode-alist' does
- not indicate which major mode to use.
-
- - Function: hack-local-variables &optional FORCE
- This function parses, and binds or evaluates as appropriate, any
- local variables for the current buffer.
-
- The handling of `enable-local-variables' documented for
- `normal-mode' actually takes place here. The argument FORCE
- usually comes from the argument FIND-FILE given to `normal-mode'.
-
-\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
-`mode-line-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 list, a symbol, or a string. If the
-value is a list, each element may be a list, a symbol, or a string.
-
-`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 used 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.
-
-`(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")'.
-
- 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::).
-
-`%['
- 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: (emacs)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.
-
projects / chise / xemacs-chise.git- / blobdiff