Foundation instead of in the original English.
\1f
+File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols
+
+CDE dt
+------
+
+ CDE stands for Common Desktop Environment. It is based on the Motif
+widget library. It's drag'n'drop protocol is also an abstraction of the
+Motif protocol (so it might be possible, that XEmacs will also support
+the Motif protocol soon).
+
+ CDE has three different types: file, buffer, and text. XEmacs only
+uses file and buffer drags. The API will disallow full URL drags, only
+file method URLs are passed through.
+
+ Buffer drags are always converted to plain text.
+
+\1f
+File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
+
+MSWindows OLE
+-------------
+
+ Only allows file drags and drops.
+
+\1f
+File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols
+
+Loose ends
+----------
+
+ The following protocols will be supported soon: Xdnd, Motif, Xde (if
+I get some specs), KDE OffiX (if KDE can find XEmacs windows).
+
+ In particular Xdnd will be one of the protocols that can benefit from
+the XEmacs API, cause it also uses MIME types to encode dragged data.
+
+\1f
+File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop
+
+Drop Interface
+==============
+
+ For each activated low-level protocol, a internal routine will catch
+incoming drops and convert them to a dragdrop-drop type misc-user-event.
+
+ This misc-user-event has its function argument set to
+`dragdrop-drop-dispatch' and the object contains the data of the drop
+(converted to URL/MIME specific data). This function will search the
+variable `experimental-dragdrop-drop-functions' for a function that can
+handle the dropped data.
+
+ To modify the drop behavior, the user can modify the variable
+`experimental-dragdrop-drop-functions'. Each element of this list
+specifies a possible handler for dropped data. The first one that can
+handle the data will return `t' and exit. Another possibility is to set
+a extent-property with the same name. Extents are checked prior to the
+variable.
+
+ The customization group `drag-n-drop' shows all variables of user
+interest.
+
+\1f
+File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
+
+Drag Interface
+==============
+
+ This describes the drag API (not implemented yet).
+
+\1f
+File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top
+
+Major and Minor Modes
+*********************
+
+ A "mode" is a set of definitions that customize XEmacs and can be
+turned on and off while you edit. There are two varieties of modes:
+"major modes", which are mutually exclusive and used for editing
+particular kinds of text, and "minor modes", which provide features
+that users can enable individually.
+
+ This chapter describes how to write both major and minor modes, how
+to indicate them in the modeline, and how they run hooks supplied by the
+user. For related topics such as keymaps and syntax tables, see *Note
+Keymaps::, and *Note Syntax Tables::.
+
+* Menu:
+
+* Major Modes:: Defining major modes.
+* Minor Modes:: Defining minor modes.
+* Modeline Format:: Customizing the text that appears in the modeline.
+* Hooks:: How to use hooks; how to write code that provides hooks.
+
+\1f
+File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes
+
+Major Modes
+===========
+
+ Major modes specialize XEmacs for editing particular kinds of text.
+Each buffer has only one major mode at a time.
+
+ The least specialized major mode is called "Fundamental mode". This
+mode has no mode-specific definitions or variable settings, so each
+XEmacs command behaves in its default manner, and each option is in its
+default state. All other major modes redefine various keys and options.
+For example, Lisp Interaction mode provides special key bindings for
+<LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
+keys.
+
+ When you need to write several editing commands to help you perform a
+specialized editing task, creating a new major mode is usually a good
+idea. In practice, writing a major mode is easy (in contrast to
+writing a minor mode, which is often difficult).
+
+ If the new mode is similar to an old one, it is often unwise to
+modify the old one to serve two purposes, since it may become harder to
+use and maintain. Instead, copy and rename an existing major mode
+definition and alter the copy--or define a "derived mode" (*note
+Derived Modes::). For example, Rmail Edit mode, which is in
+`emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
+mode except that it provides three additional commands. Its definition
+is distinct from that of Text mode, but was derived from it.
+
+ Rmail Edit mode is an example of a case where one piece of text is
+put temporarily into a different major mode so it can be edited in a
+different way (with ordinary XEmacs commands rather than Rmail). In
+such cases, the temporary major mode usually has a command to switch
+back to the buffer's usual mode (Rmail mode, in this case). You might
+be tempted to present the temporary redefinitions inside a recursive
+edit and restore the usual ones when the user exits; but this is a bad
+idea because it constrains the user's options when it is done in more
+than one buffer: recursive edits must be exited most-recently-entered
+first. Using alternative major modes avoids this limitation. *Note
+Recursive Editing::.
+
+ The standard XEmacs Lisp library directory contains the code for
+several major modes, in files including `text-mode.el', `texinfo.el',
+`lisp-mode.el', `c-mode.el', and `rmail.el'. You can look at these
+libraries to see how modes are written. Text mode is perhaps the
+simplest major mode aside from Fundamental mode. Rmail mode is a
+complicated and specialized mode.
+
+* Menu:
+
+* Major Mode Conventions:: Coding conventions for keymaps, etc.
+* Example Major Modes:: Text mode and Lisp modes.
+* Auto Major Mode:: How XEmacs chooses the major mode automatically.
+* Mode Help:: Finding out how to use a mode.
+* Derived Modes:: Defining a new major mode based on another major
+ mode.
+
+\1f
+File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes
+
+Major Mode Conventions
+----------------------
+
+ The code for existing major modes follows various coding conventions,
+including conventions for local keymap and syntax table initialization,
+global names, and hooks. Please follow these conventions when you
+define a new major mode:
+
+ * Define a command whose name ends in `-mode', with no arguments,
+ that switches to the new mode in the current buffer. This command
+ should set up the keymap, syntax table, and local variables in an
+ existing buffer without changing the buffer's text.
+
+ * Write a documentation string for this command that describes the
+ special commands available in this mode. `C-h m'
+ (`describe-mode') in your mode will display this string.
+
+ The documentation string may include the special documentation
+ substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
+ enable the documentation to adapt automatically to the user's own
+ key bindings. *Note Keys in Documentation::.
+
+ * The major mode command should start by calling
+ `kill-all-local-variables'. This is what gets rid of the local
+ variables of the major mode previously in effect.
+
+ * The major mode command should set the variable `major-mode' to the
+ major mode command symbol. This is how `describe-mode' discovers
+ which documentation to print.
+
+ * The major mode command should set the variable `mode-name' to the
+ "pretty" name of the mode, as a string. This appears in the mode
+ line.
+
+ * Since all global names are in the same name space, all the global
+ variables, constants, and functions that are part of the mode
+ should have names that start with the major mode name (or with an
+ abbreviation of it if the name is long). *Note Style Tips::.
+
+ * The major mode should usually have its own keymap, which is used
+ as the local keymap in all buffers in that mode. The major mode
+ function should call `use-local-map' to install this local map.
+ *Note Active Keymaps::, for more information.
+
+ This keymap should be kept in a global variable named
+ `MODENAME-mode-map'. Normally the library that defines the mode
+ sets this variable.
+
+ * The mode may have its own syntax table or may share one with other
+ related modes. If it has its own syntax table, it should store
+ this in a variable named `MODENAME-mode-syntax-table'. *Note
+ Syntax Tables::.
+
+ * The mode may have its own abbrev table or may share one with other
+ related modes. If it has its own abbrev table, it should store
+ this in a variable named `MODENAME-mode-abbrev-table'. *Note
+ Abbrev Tables::.
+
+ * Use `defvar' to set mode-related variables, so that they are not
+ reinitialized if they already have a value. (Such reinitialization
+ could discard customizations made by the user.)
+
+ * To make a buffer-local binding for an Emacs customization
+ variable, use `make-local-variable' in the major mode command, not
+ `make-variable-buffer-local'. The latter function would make the
+ variable local to every buffer in which it is subsequently set,
+ which would affect buffers that do not use this mode. It is
+ undesirable for a mode to have such global effects. *Note
+ Buffer-Local Variables::.
+
+ It's ok to use `make-variable-buffer-local', if you wish, for a
+ variable used only within a single Lisp package.
+
+ * Each major mode should have a "mode hook" named
+ `MODENAME-mode-hook'. The major mode command should run that
+ hook, with `run-hooks', as the very last thing it does. *Note
+ Hooks::.
+
+ * The major mode command may also run the hooks of some more basic
+ modes. For example, `indented-text-mode' runs `text-mode-hook' as
+ well as `indented-text-mode-hook'. It may run these other hooks
+ immediately before the mode's own hook (that is, after everything
+ else), or it may run them earlier.
+
+ * If something special should be done if the user switches a buffer
+ from this mode to any other major mode, the mode can set a local
+ value for `change-major-mode-hook'.
+
+ * If this mode is appropriate only for specially-prepared text, then
+ the major mode command symbol should have a property named
+ `mode-class' with value `special', put on as follows:
+
+ (put 'funny-mode 'mode-class 'special)
+
+ This tells XEmacs that new buffers created while the current
+ buffer has Funny mode should not inherit Funny mode. Modes such
+ as Dired, Rmail, and Buffer List use this feature.
+
+ * If you want to make the new mode the default for files with certain
+ recognizable names, add an element to `auto-mode-alist' to select
+ the mode for those file names. If you define the mode command to
+ autoload, you should add this element in the same file that calls
+ `autoload'. Otherwise, it is sufficient to add the element in the
+ file that contains the mode definition. *Note Auto Major Mode::.
+
+ * In the documentation, you should provide a sample `autoload' form
+ and an example of how to add to `auto-mode-alist', that users can
+ include in their `.emacs' files.
+
+ * The top-level forms in the file defining the mode should be
+ written so that they may be evaluated more than once without
+ adverse consequences. Even if you never load the file more than
+ once, someone else will.
+
+ - Variable: change-major-mode-hook
+ This normal hook is run by `kill-all-local-variables' before it
+ does anything else. This gives major modes a way to arrange for
+ something special to be done if the user switches to a different
+ major mode. For best results, make this variable buffer-local, so
+ that it will disappear after doing its job and will not interfere
+ with the subsequent major mode. *Note Hooks::.
+
+\1f
+File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes
+
+Major Mode Examples
+-------------------
+
+ Text mode is perhaps the simplest mode besides Fundamental mode.
+Here are excerpts from `text-mode.el' that illustrate many of the
+conventions listed above:
+
+ ;; Create mode-specific tables.
+ (defvar text-mode-syntax-table nil
+ "Syntax table used while in text mode.")
+
+ (if text-mode-syntax-table
+ () ; Do not change the table if it is already set up.
+ (setq text-mode-syntax-table (make-syntax-table))
+ (modify-syntax-entry ?\" ". " text-mode-syntax-table)
+ (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
+ (modify-syntax-entry ?' "w " text-mode-syntax-table))
+
+ (defvar text-mode-abbrev-table nil
+ "Abbrev table used while in text mode.")
+ (define-abbrev-table 'text-mode-abbrev-table ())
+
+ (defvar text-mode-map nil) ; Create a mode-specific keymap.
+
+ (if text-mode-map
+ () ; Do not change the keymap if it is already set up.
+ (setq text-mode-map (make-sparse-keymap))
+ (define-key text-mode-map "\t" 'tab-to-tab-stop)
+ (define-key text-mode-map "\es" 'center-line)
+ (define-key text-mode-map "\eS" 'center-paragraph))
+
+ Here is the complete major mode function definition for Text mode:
+
+ (defun text-mode ()
+ "Major mode for editing text intended for humans to read.
+ Special commands: \\{text-mode-map}
+ Turning on text-mode runs the hook `text-mode-hook'."
+ (interactive)
+ (kill-all-local-variables)
+ (use-local-map text-mode-map) ; This provides the local keymap.
+ (setq mode-name "Text") ; This name goes into the modeline.
+ (setq major-mode 'text-mode) ; This is how `describe-mode'
+ ; finds the doc string to print.
+ (setq local-abbrev-table text-mode-abbrev-table)
+ (set-syntax-table text-mode-syntax-table)
+ (run-hooks 'text-mode-hook)) ; Finally, this permits the user to
+ ; customize the mode with a hook.
+
+ The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
+Interaction mode) have more features than Text mode and the code is
+correspondingly more complicated. Here are excerpts from
+`lisp-mode.el' that illustrate how these modes are written.
+
+ ;; Create mode-specific table variables.
+ (defvar lisp-mode-syntax-table nil "")
+ (defvar emacs-lisp-mode-syntax-table nil "")
+ (defvar lisp-mode-abbrev-table nil "")
+
+ (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
+ ; if it is already set.
+ (let ((i 0))
+ (setq emacs-lisp-mode-syntax-table (make-syntax-table))
+
+ ;; Set syntax of chars up to 0 to class of chars that are
+ ;; part of symbol names but not words.
+ ;; (The number 0 is `48' in the ASCII character set.)
+ (while (< i ?0)
+ (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
+ (setq i (1+ i)))
+ ...
+ ;; Set the syntax for other characters.
+ (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
+ (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
+ ...
+ (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
+ (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
+ ...))
+ ;; Create an abbrev table for lisp-mode.
+ (define-abbrev-table 'lisp-mode-abbrev-table ())
+
+ Much code is shared among the three Lisp modes. The following
+function sets various variables; it is called by each of the major Lisp
+mode functions:
+
+ (defun lisp-mode-variables (lisp-syntax)
+ ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
+ ;; and `t' in the other two Lisp modes.
+ (cond (lisp-syntax
+ (if (not lisp-mode-syntax-table)
+ ;; The Emacs Lisp mode syntax table always exists, but
+ ;; the Lisp Mode syntax table is created the first time a
+ ;; mode that needs it is called. This is to save space.
+ (progn (setq lisp-mode-syntax-table
+ (copy-syntax-table emacs-lisp-mode-syntax-table))
+ ;; Change some entries for Lisp mode.
+ (modify-syntax-entry ?\| "\" "
+ lisp-mode-syntax-table)
+ (modify-syntax-entry ?\[ "_ "
+ lisp-mode-syntax-table)
+ (modify-syntax-entry ?\] "_ "
+ lisp-mode-syntax-table)))
+ (set-syntax-table lisp-mode-syntax-table)))
+ (setq local-abbrev-table lisp-mode-abbrev-table)
+ ...)
+
+ Functions such as `forward-paragraph' use the value of the
+`paragraph-start' variable. Since Lisp code is different from ordinary
+text, the `paragraph-start' variable needs to be set specially to
+handle Lisp. Also, comments are indented in a special fashion in Lisp
+and the Lisp modes need their own mode-specific
+`comment-indent-function'. The code to set these variables is the rest
+of `lisp-mode-variables'.
+
+ (make-local-variable 'paragraph-start)
+ ;; Having `^' is not clean, but `page-delimiter'
+ ;; has them too, and removing those is a pain.
+ (setq paragraph-start (concat "^$\\|" page-delimiter))
+ ...
+ (make-local-variable 'comment-indent-function)
+ (setq comment-indent-function 'lisp-comment-indent))
+
+ Each of the different Lisp modes has a slightly different keymap.
+For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
+Lisp modes do not. However, all Lisp modes have some commands in
+common. The following function adds these common commands to a given
+keymap.
+
+ (defun lisp-mode-commands (map)
+ (define-key map "\e\C-q" 'indent-sexp)
+ (define-key map "\177" 'backward-delete-char-untabify)
+ (define-key map "\t" 'lisp-indent-line))
+
+ Here is an example of using `lisp-mode-commands' to initialize a
+keymap, as part of the code for Emacs Lisp mode. First we declare a
+variable with `defvar' to hold the mode-specific keymap. When this
+`defvar' executes, it sets the variable to `nil' if it was void. Then
+we set up the keymap if the variable is `nil'.
+
+ This code avoids changing the keymap or the variable if it is already
+set up. This lets the user customize the keymap.
+
+ (defvar emacs-lisp-mode-map () "")
+ (if emacs-lisp-mode-map
+ ()
+ (setq emacs-lisp-mode-map (make-sparse-keymap))
+ (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
+ (lisp-mode-commands emacs-lisp-mode-map))
+
+ Finally, here is the complete major mode function definition for
+Emacs Lisp mode.
+
+ (defun emacs-lisp-mode ()
+ "Major mode for editing Lisp code to run in XEmacs.
+ Commands:
+ Delete converts tabs to spaces as it moves back.
+ Blank lines separate paragraphs. Semicolons start comments.
+ \\{emacs-lisp-mode-map}
+ Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+ (interactive)
+ (kill-all-local-variables)
+ (use-local-map emacs-lisp-mode-map) ; This provides the local keymap.
+ (set-syntax-table emacs-lisp-mode-syntax-table)
+ (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
+ ; finds out what to describe.
+ (setq mode-name "Emacs-Lisp") ; This goes into the modeline.
+ (lisp-mode-variables nil) ; This defines various variables.
+ (run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a
+ ; hook to customize the mode.
+
+\1f
File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes
How XEmacs Chooses a Major Mode
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
+`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::).
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.
+ 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
`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.
+ 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
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
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