Techniques for XEmacs Developers
================================
- To make a quantified XEmacs, do: `make quantmacs'.
+ To make a purified XEmacs, do: `make puremacs'. To make a
+quantified XEmacs, do: `make quantmacs'.
- You simply can't dump Quantified and Purified images. Run the image
-like so: `quantmacs -batch -l loadup.el run-temacs XEMACS-ARGS...'.
+ You simply can't dump Quantified and Purified images (unless using
+the portable dumper). Purify gets confused when xemacs frees memory in
+one process that was allocated in a _different_ process on a different
+machine!. Run it like so:
+ temacs -batch -l loadup.el run-temacs XEMACS-ARGS...
Before you go through the trouble, are you compiling with all
-debugging and error-checking off? If not try that first. Be warned
+debugging and error-checking off? If not, try that first. Be warned
that while Quantify is directly responsible for quite a few
optimizations which have been made to XEmacs, doing a run which
generates results which can be acted upon is not necessarily a trivial
Function calls in elisp are especially expensive. Iterating over a
long list is going to be 30 times faster implemented in C than in Elisp.
+ Heavily used small code fragments need to be fast. The traditional
+way to implement such code fragments in C is with macros. But macros
+in C are known to be broken.
+
+ Macro arguments that are repeatedly evaluated may suffer from
+repeated side effects or suboptimal performance.
+
+ Variable names used in macros may collide with caller's variables,
+causing (at least) unwanted compiler warnings.
+
+ In order to solve these problems, and maintain statement semantics,
+one should use the `do { ... } while (0)' trick while trying to
+reference macro arguments exactly once using local variables.
+
+ Let's take a look at this poor macro definition:
+
+ #define MARK_OBJECT(obj) \
+ if (!marked_p (obj)) mark_object (obj), did_mark = 1
+
+ This macro evaluates its argument twice, and also fails if used like
+this:
+ if (flag) MARK_OBJECT (obj); else do_something();
+
+ A much better definition is
+
+ #define MARK_OBJECT(obj) do { \
+ Lisp_Object mo_obj = (obj); \
+ if (!marked_p (mo_obj)) \
+ { \
+ mark_object (mo_obj); \
+ did_mark = 1; \
+ } \
+ } while (0)
+
+ Notice the elimination of double evaluation by using the local
+variable with the obscure name. Writing safe and efficient macros
+requires great care. The one problem with macros that cannot be
+portably worked around is, since a C block has no value, a macro used
+as an expression rather than a statement cannot use the techniques just
+described to avoid multiple evaluation.
+
+ In most cases where a macro has function semantics, an inline
+function is a better implementation technique. Modern compiler
+optimizers tend to inline functions even if they have no `inline'
+keyword, and configure magic ensures that the `inline' keyword can be
+safely used as an additional compiler hint. Inline functions used in a
+single .c files are easy. The function must already be defined to be
+`static'. Just add another `inline' keyword to the definition.
+
+ inline static int
+ heavily_used_small_function (int arg)
+ {
+ ...
+ }
+
+ Inline functions in header files are trickier, because we would like
+to make the following optimization if the function is _not_ inlined
+(for example, because we're compiling for debugging). We would like the
+function to be defined externally exactly once, and each calling
+translation unit would create an external reference to the function,
+instead of including a definition of the inline function in the object
+code of every translation unit that uses it. This optimization is
+currently only available for gcc. But you don't have to worry about the
+trickiness; just define your inline functions in header files using this
+pattern:
+
+ INLINE_HEADER int
+ i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg);
+ INLINE_HEADER int
+ i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg)
+ {
+ ...
+ }
+
+ The declaration right before the definition is to prevent warnings
+when compiling with `gcc -Wmissing-declarations'. I consider issuing
+this warning for inline functions a gcc bug, but the gcc maintainers
+disagree.
+
+ Every header which contains inline functions, either directly by
+using `INLINE_HEADER' or indirectly by using `DECLARE_LRECORD' must be
+added to `inline.c''s includes to make the optimization described above
+work. (Optimization note: if all INLINE_HEADER functions are in fact
+inlined in all translation units, then the linker can just discard
+`inline.o', since it contains only unreferenced code).
+
To get started debugging XEmacs, take a look at the `.gdbinit' and
-`.dbxrc' files in the `src' directory. *Note Q2.1.15 - How to Debug an
-XEmacs problem with a debugger: (xemacs-faq)Q2.1.15 - How to Debug an
-XEmacs problem with a debugger.
+`.dbxrc' files in the `src' directory. See the section in the XEmacs
+FAQ on How to Debug an XEmacs problem with a debugger.
After making source code changes, run `make check' to ensure that
-you haven't introduced any regressions. If you're feeling ambitious,
-you can try to improve the test suite in `tests/automated'.
+you haven't introduced any regressions. If you want to make xemacs more
+reliable, please improve the test suite in `tests/automated'.
+
+ Did you make sure you didn't introduce any new compiler warnings?
+
+ Before submitting a patch, please try compiling at least once with
+
+ configure --with-mule --with-union-type --error-checking=all
Here are things to know when you create a new source file:
* Header files should _not_ include `<config.h>' and `"lisp.h"'. It
is the responsibility of the `.c' files that use it to do so.
- * If the header uses `INLINE', either directly or through
- `DECLARE_LRECORD', then it must be added to `inline.c''s includes.
-
- * Try compiling at least once with
-
- gcc --with-mule --with-union-type --error-checking=all
-
- * Did I mention that you should run the test suite?
- make check
Here is a checklist of things to do when creating a new lisp object
type named FOO:
2. create FOO.c
- 3. add definitions of syms_of_FOO, etc. to FOO.c
+ 3. add definitions of `syms_of_FOO', etc. to `FOO.c'
+
+ 4. add declarations of `syms_of_FOO', etc. to `symsinit.h'
- 4. add declarations of syms_of_FOO, etc. to symsinit.h
+ 5. add calls to `syms_of_FOO', etc. to `emacs.c'
- 5. add calls to syms_of_FOO, etc. to emacs.c(main_1)
+ 6. add definitions of macros like `CHECK_FOO' and `FOOP' to `FOO.h'
- 6. add definitions of macros like CHECK_FOO and FOOP to FOO.h
+ 7. add the new type index to `enum lrecord_type'
- 7. add the new type index to enum lrecord_type
+ 8. add a DEFINE_LRECORD_IMPLEMENTATION call to `FOO.c'
- 8. add DEFINE_LRECORD_IMPLEMENTATION call to FOO.c
+ 9. add an INIT_LRECORD_IMPLEMENTATION call to `syms_of_FOO.c'
\1f
File: internals.info, Node: A Summary of the Various XEmacs Modules, Next: Allocation of Objects in XEmacs Lisp, Prev: Rules When Writing New C Code, Up: Top
These files provide some miscellaneous TTY-output functions and
should probably be merged into `redisplay-tty.c'.
-\1f
-File: internals.info, Node: Modules for Interfacing with the File System, Next: Modules for Other Aspects of the Lisp Interpreter and Object System, Prev: Modules for the Redisplay Mechanism, Up: A Summary of the Various XEmacs Modules
-
-Modules for Interfacing with the File System
-============================================
-
- lstream.c
- lstream.h
-
- These modules implement the "stream" Lisp object type. This is an
-internal-only Lisp object that implements a generic buffering stream.
-The idea is to provide a uniform interface onto all sources and sinks of
-data, including file descriptors, stdio streams, chunks of memory, Lisp
-buffers, Lisp strings, etc. That way, I/O functions can be written to
-the stream interface and can transparently handle all possible sources
-and sinks. (For example, the `read' function can read data from a
-file, a string, a buffer, or even a function that is called repeatedly
-to return data, without worrying about where the data is coming from or
-what-size chunks it is returned in.)
-
- Note that in the C code, streams are called "lstreams" (for "Lisp
-streams") to distinguish them from other kinds of streams, e.g. stdio
-streams and C++ I/O streams.
-
- Similar to other subsystems in XEmacs, lstreams are separated into
-generic functions and a set of methods for the different types of
-lstreams. `lstream.c' provides implementations of many different types
-of streams; others are provided, e.g., in `mule-coding.c'.
-
- fileio.c
-
- This implements the basic primitives for interfacing with the file
-system. This includes primitives for reading files into buffers,
-writing buffers into files, checking for the presence or accessibility
-of files, canonicalizing file names, etc. Note that these primitives
-are usually not invoked directly by the user: There is a great deal of
-higher-level Lisp code that implements the user commands such as
-`find-file' and `save-buffer'. This is similar to the distinction
-between the lower-level primitives in `editfns.c' and the higher-level
-user commands in `commands.c' and `simple.el'.
-
- filelock.c
-
- This file provides functions for detecting clashes between different
-processes (e.g. XEmacs and some external process, or two different
-XEmacs processes) modifying the same file. (XEmacs can optionally use
-the `lock/' subdirectory to provide a form of "locking" between
-different XEmacs processes.) This module is also used by the low-level
-functions in `insdel.c' to ensure that, if the first modification is
-being made to a buffer whose corresponding file has been externally
-modified, the user is made aware of this so that the buffer can be
-synched up with the external changes if necessary.
-
- filemode.c
-
- This file provides some miscellaneous functions that construct a
-`rwxr-xr-x'-type permissions string (as might appear in an `ls'-style
-directory listing) given the information returned by the `stat()'
-system call.
-
- dired.c
- ndir.h
-
- These files implement the XEmacs interface to directory searching.
-This includes a number of primitives for determining the files in a
-directory and for doing filename completion. (Remember that generic
-completion is handled by a different mechanism, in `minibuf.c'.)
-
- `ndir.h' is a header file used for the directory-searching emulation
-functions provided in `sysdep.c' (see section J below), for systems
-that don't provide any directory-searching functions. (On those
-systems, directories can be read directly as files, and parsed.)
-
- realpath.c
-
- This file provides an implementation of the `realpath()' function
-for expanding symbolic links, on systems that don't implement it or have
-a broken implementation.
-
Foundation instead of in the original English.
\1f
+File: internals.info, Node: Modules for Interfacing with the File System, Next: Modules for Other Aspects of the Lisp Interpreter and Object System, Prev: Modules for the Redisplay Mechanism, Up: A Summary of the Various XEmacs Modules
+
+Modules for Interfacing with the File System
+============================================
+
+ lstream.c
+ lstream.h
+
+ These modules implement the "stream" Lisp object type. This is an
+internal-only Lisp object that implements a generic buffering stream.
+The idea is to provide a uniform interface onto all sources and sinks of
+data, including file descriptors, stdio streams, chunks of memory, Lisp
+buffers, Lisp strings, etc. That way, I/O functions can be written to
+the stream interface and can transparently handle all possible sources
+and sinks. (For example, the `read' function can read data from a
+file, a string, a buffer, or even a function that is called repeatedly
+to return data, without worrying about where the data is coming from or
+what-size chunks it is returned in.)
+
+ Note that in the C code, streams are called "lstreams" (for "Lisp
+streams") to distinguish them from other kinds of streams, e.g. stdio
+streams and C++ I/O streams.
+
+ Similar to other subsystems in XEmacs, lstreams are separated into
+generic functions and a set of methods for the different types of
+lstreams. `lstream.c' provides implementations of many different types
+of streams; others are provided, e.g., in `mule-coding.c'.
+
+ fileio.c
+
+ This implements the basic primitives for interfacing with the file
+system. This includes primitives for reading files into buffers,
+writing buffers into files, checking for the presence or accessibility
+of files, canonicalizing file names, etc. Note that these primitives
+are usually not invoked directly by the user: There is a great deal of
+higher-level Lisp code that implements the user commands such as
+`find-file' and `save-buffer'. This is similar to the distinction
+between the lower-level primitives in `editfns.c' and the higher-level
+user commands in `commands.c' and `simple.el'.
+
+ filelock.c
+
+ This file provides functions for detecting clashes between different
+processes (e.g. XEmacs and some external process, or two different
+XEmacs processes) modifying the same file. (XEmacs can optionally use
+the `lock/' subdirectory to provide a form of "locking" between
+different XEmacs processes.) This module is also used by the low-level
+functions in `insdel.c' to ensure that, if the first modification is
+being made to a buffer whose corresponding file has been externally
+modified, the user is made aware of this so that the buffer can be
+synched up with the external changes if necessary.
+
+ filemode.c
+
+ This file provides some miscellaneous functions that construct a
+`rwxr-xr-x'-type permissions string (as might appear in an `ls'-style
+directory listing) given the information returned by the `stat()'
+system call.
+
+ dired.c
+ ndir.h
+
+ These files implement the XEmacs interface to directory searching.
+This includes a number of primitives for determining the files in a
+directory and for doing filename completion. (Remember that generic
+completion is handled by a different mechanism, in `minibuf.c'.)
+
+ `ndir.h' is a header file used for the directory-searching emulation
+functions provided in `sysdep.c' (see section J below), for systems
+that don't provide any directory-searching functions. (On those
+systems, directories can be read directly as files, and parsed.)
+
+ realpath.c
+
+ This file provides an implementation of the `realpath()' function
+for expanding symbolic links, on systems that don't implement it or have
+a broken implementation.
+
+\1f
File: internals.info, Node: Modules for Other Aspects of the Lisp Interpreter and Object System, Next: Modules for Interfacing with the Operating System, Prev: Modules for Interfacing with the File System, Up: A Summary of the Various XEmacs Modules
Modules for Other Aspects of the Lisp Interpreter and Object System
All lrecords have at the beginning of their structure a `struct
lrecord_header'. This just contains a type number and some flags,
-including the mark bit. The type number, thru the
+including the mark bit. All builtin type numbers are defined as
+constants in `enum lrecord_type', to allow the compiler to generate
+more efficient code for `TYPEP'. The type number, thru the
`lrecord_implementation_table', gives access to a `struct
lrecord_implementation', which is a structure containing method pointers
and such. There is one of these for each type, and it is a global,
Whenever you create an lrecord, you need to call either
`DEFINE_LRECORD_IMPLEMENTATION()' or
`DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()'. This needs to be specified
-in a C file, at the top level. What this actually does is define and
-initialize the implementation structure for the lrecord. (And possibly
-declares a function `error_check_foo()' that implements the `XFOO()'
-macro when error-checking is enabled.) The arguments to the macros are
-the actual type name (this is used to construct the C variable name of
-the lrecord implementation structure and related structures using the
-`##' macro concatenation operator), a string that names the type on the
-Lisp level (this may not be the same as the C type name; typically, the
-C type name has underscores, while the Lisp string has dashes), various
-method pointers, and the name of the C structure that contains the
-object. The methods are used to encapsulate type-specific information
-about the object, such as how to print it or mark it for garbage
-collection, so that it's easy to add new object types without having to
-add a specific case for each new type in a bunch of different places.
+in a `.c' file, at the top level. What this actually does is define
+and initialize the implementation structure for the lrecord. (And
+possibly declares a function `error_check_foo()' that implements the
+`XFOO()' macro when error-checking is enabled.) The arguments to the
+macros are the actual type name (this is used to construct the C
+variable name of the lrecord implementation structure and related
+structures using the `##' macro concatenation operator), a string that
+names the type on the Lisp level (this may not be the same as the C
+type name; typically, the C type name has underscores, while the Lisp
+string has dashes), various method pointers, and the name of the C
+structure that contains the object. The methods are used to
+encapsulate type-specific information about the object, such as how to
+print it or mark it for garbage collection, so that it's easy to add
+new object types without having to add a specific case for each new
+type in a bunch of different places.
The difference between `DEFINE_LRECORD_IMPLEMENTATION()' and
`DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()' is that the former is used
For the purpose of keeping allocation statistics, the allocation
engine keeps a list of all the different types that exist. Note that,
since `DEFINE_LRECORD_IMPLEMENTATION()' is a macro that is specified at
-top-level, there is no way for it to add to the list of all existing
-types. What happens instead is that each implementation structure
-contains in it a dynamically assigned number that is particular to that
-type. (Or rather, it contains a pointer to another structure that
-contains this number. This evasiveness is done so that the
-implementation structure can be declared const.) In the sweep stage of
-garbage collection, each lrecord is examined to see if its
-implementation structure has its dynamically-assigned number set. If
-not, it must be a new type, and it is added to the list of known types
-and a new number assigned. The number is used to index into an array
-holding the number of objects of each type and the total memory
-allocated for objects of that type. The statistics in this array are
-also computed during the sweep stage. These statistics are returned by
-the call to `garbage-collect' and are printed out at the end of the
-loadup phase.
+top-level, there is no way for it to initialize the global data
+structures containing type information, like
+`lrecord_implementations_table'. For this reason a call to
+`INIT_LRECORD_IMPLEMENTATION' must be added to the same source file
+containing `DEFINE_LRECORD_IMPLEMENTATION', but instead of to the top
+level, to one of the init functions, typically `syms_of_FOO.c'.
+`INIT_LRECORD_IMPLEMENTATION' must be called before an object of this
+type is used.
+
+ The type number is also used to index into an array holding the
+number of objects of each type and the total memory allocated for
+objects of that type. The statistics in this array are computed during
+the sweep stage. These statistics are returned by the call to
+`garbage-collect'.
Note that for every type defined with a `DEFINE_LRECORD_*()' macro,
there needs to be a `DECLARE_LRECORD_IMPLEMENTATION()' somewhere in a
the memory warnings are not functional.)
Allocated memory that is going to be used to make a Lisp object is
-created using `allocate_lisp_storage()'. This calls `xmalloc()' but
-also verifies that the pointer to the memory can fit into a Lisp word
-(remember that some bits are taken away for a type tag and a mark bit).
-If not, an error is issued through `memory_full()'.
+created using `allocate_lisp_storage()'. This just calls `xmalloc()'.
+It used to verify that the pointer to the memory can fit into a Lisp
+word, before the current Lisp object representation was introduced.
`allocate_lisp_storage()' is called by `alloc_lcrecord()',
`ALLOCATE_FIXED_TYPE()', and the vector and bit-vector creation
routines. These routines also call `INCREMENT_CONS_COUNTER()' at the
from the minibuffer on other occasions. However, if user is
supposed to edit default value, INITIAL-CONTENTS may be preferred.
- - Function: read-string prompt &optional initial history
+ - Function: read-string prompt &optional initial history default-value
This function reads a string from the minibuffer and returns it.
The arguments PROMPT and INITIAL are used as in
`read-from-minibuffer'. The keymap used is `minibuffer-local-map'.
The optional argument HISTORY, if non-nil, specifies a history
- list and optionally the initial position in the list.
+ list and optionally the initial position in the list. The optional
+ argument DEFAULT specifies a default value to return if the user
+ enters null input; it should be a string.
This function is a simplified interface to the
`read-from-minibuffer' function:
- (read-string PROMPT INITIAL)
+ (read-string PROMPT INITIAL HISTORY DEFAULT)
==
- (read-from-minibuffer PROMPT INITIAL nil nil nil)
+ (read-from-minibuffer PROMPT INITIAL nil nil
+ HISTORY nil DEFAULT)))
- Variable: minibuffer-local-map
This is the default local keymap for reading from the minibuffer.
This section describes functions for reading Lisp objects with the
minibuffer.
- - Function: read-minibuffer prompt &optional initial
+ - Function: read-expression prompt &optional initial history
+ default-value
This function reads a Lisp object using the minibuffer, and
returns it without evaluating it. The arguments PROMPT and
INITIAL are used as in `read-from-minibuffer'.
+ The optional argument HISTORY, if non-nil, specifies a history
+ list and optionally the initial position in the list. The optional
+ argument DEFAULT-VALUE specifies a default value to return if the
+ user enters null input; it should be a string.
+
This is a simplified interface to the `read-from-minibuffer'
function:
- (read-minibuffer PROMPT INITIAL)
+ (read-expression PROMPT INITIAL HISTORY DEFAULT-VALUE)
==
- (read-from-minibuffer PROMPT INITIAL nil t)
+ (read-from-minibuffer PROMPT INITIAL nil t
+ HISTORY nil DEFAULT-VALUE)
Here is an example in which we supply the string `"(testing)"' as
initial input:
- (read-minibuffer
+ (read-expression
"Enter an expression: " (format "%s" '(testing)))
;; Here is how the minibuffer is displayed:
The user can type <RET> immediately to use the initial input as a
default, or can edit the input.
- - Function: eval-minibuffer prompt &optional initial
+ - Function: read-minibuffer prompt &optional initial history
+ default-value
+ This is a FSF Emacs compatible function. Use `read-expression'
+ instead.
+
+ - Function: eval-minibuffer prompt &optional initial history
+ default-value
This function reads a Lisp expression using the minibuffer,
evaluates it, then returns the result. The arguments PROMPT and
INITIAL are used as in `read-from-minibuffer'.
+ The optional argument HISTORY, if non-nil, specifies a history
+ list and optionally the initial position in the list. The optional
+ argument DEFAULT-VALUE specifies a default value to return if the
+ user enters null input; it should be a string.
+
This function simply evaluates the result of a call to
- `read-minibuffer':
+ `read-expression':
(eval-minibuffer PROMPT INITIAL)
==
- (eval (read-minibuffer PROMPT INITIAL))
+ (eval (read-expression PROMPT INITIAL))
- - Function: edit-and-eval-command prompt form
+ - Function: edit-and-eval-command prompt command &optional history
This function reads a Lisp expression in the minibuffer, and then
evaluates it. The difference between this command and
- `eval-minibuffer' is that here the initial FORM is not optional
+ `eval-minibuffer' is that here the initial COMMAND is not optional
and it is treated as a Lisp object to be converted to printed
representation rather than as a string of text. It is printed with
`prin1', so if it is a string, double-quote characters (`"')
the value of REQUIRE-MATCH, and regardless of whether the empty
string is included in COLLECTION.
- The function `completing-read' works by calling `read-minibuffer'.
+ The function `completing-read' works by calling `read-expression'.
It uses `minibuffer-local-completion-map' as the keymap if
REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map'
if REQUIRE-MATCH is non-`nil'. *Note Completion Commands::.
`minibuffer-completion-confirm'. For more information about them,
see *Note Completion Commands::.
-\1f
-File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
-
-Minibuffer Commands That Do Completion
---------------------------------------
-
- This section describes the keymaps, commands and user options used in
-the minibuffer to do completion.
-
- - Variable: minibuffer-local-completion-map
- `completing-read' uses this value as the local keymap when an
- exact match of one of the completions is not required. By
- default, this keymap makes the following bindings:
-
- `?'
- `minibuffer-completion-help'
-
- <SPC>
- `minibuffer-complete-word'
-
- <TAB>
- `minibuffer-complete'
-
- with other characters bound as in `minibuffer-local-map' (*note
- Text from Minibuffer::).
-
- - Variable: minibuffer-local-must-match-map
- `completing-read' uses this value as the local keymap when an
- exact match of one of the completions is required. Therefore, no
- keys are bound to `exit-minibuffer', the command that exits the
- minibuffer unconditionally. By default, this keymap makes the
- following bindings:
-
- `?'
- `minibuffer-completion-help'
-
- <SPC>
- `minibuffer-complete-word'
-
- <TAB>
- `minibuffer-complete'
-
- `C-j'
- `minibuffer-complete-and-exit'
-
- <RET>
- `minibuffer-complete-and-exit'
-
- with other characters bound as in `minibuffer-local-map'.
-
- - Variable: minibuffer-completion-table
- The value of this variable is the alist or obarray used for
- completion in the minibuffer. This is the global variable that
- contains what `completing-read' passes to `try-completion'. It is
- used by minibuffer completion commands such as
- `minibuffer-complete-word'.
-
- - Variable: minibuffer-completion-predicate
- This variable's value is the predicate that `completing-read'
- passes to `try-completion'. The variable is also used by the other
- minibuffer completion functions.
-
- - Command: minibuffer-complete-word
- This function completes the minibuffer contents by at most a single
- word. Even if the minibuffer contents have only one completion,
- `minibuffer-complete-word' does not add any characters beyond the
- first character that is not a word constituent. *Note Syntax
- Tables::.
-
- - Command: minibuffer-complete
- This function completes the minibuffer contents as far as possible.
-
- - Command: minibuffer-complete-and-exit
- This function completes the minibuffer contents, and exits if
- confirmation is not required, i.e., if
- `minibuffer-completion-confirm' is `nil'. If confirmation _is_
- required, it is given by repeating this command immediately--the
- command is programmed to work without confirmation when run twice
- in succession.
-
- - Variable: minibuffer-completion-confirm
- When the value of this variable is non-`nil', XEmacs asks for
- confirmation of a completion before exiting the minibuffer. The
- function `minibuffer-complete-and-exit' checks the value of this
- variable before it exits.
-
- - Command: minibuffer-completion-help
- This function creates a list of the possible completions of the
- current minibuffer contents. It works by calling `all-completions'
- using the value of the variable `minibuffer-completion-table' as
- the COLLECTION argument, and the value of
- `minibuffer-completion-predicate' as the PREDICATE argument. The
- list of completions is displayed as text in a buffer named
- `*Completions*'.
-
- - Function: display-completion-list completions
- This function displays COMPLETIONS to the stream in
- `standard-output', usually a buffer. (*Note Read and Print::, for
- more information about streams.) The argument COMPLETIONS is
- normally a list of completions just returned by `all-completions',
- but it does not have to be. Each element may be a symbol or a
- string, either of which is simply printed, or a list of two
- strings, which is printed as if the strings were concatenated.
-
- This function is called by `minibuffer-completion-help'. The most
- common way to use it is together with
- `with-output-to-temp-buffer', like this:
-
- (with-output-to-temp-buffer "*Completions*"
- (display-completion-list
- (all-completions (buffer-string) my-alist)))
-
- - User Option: completion-auto-help
- If this variable is non-`nil', the completion commands
- automatically display a list of possible completions whenever
- nothing can be completed because the next character is not
- uniquely determined.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
+
+Minibuffer Commands That Do Completion
+--------------------------------------
+
+ This section describes the keymaps, commands and user options used in
+the minibuffer to do completion.
+
+ - Variable: minibuffer-local-completion-map
+ `completing-read' uses this value as the local keymap when an
+ exact match of one of the completions is not required. By
+ default, this keymap makes the following bindings:
+
+ `?'
+ `minibuffer-completion-help'
+
+ <SPC>
+ `minibuffer-complete-word'
+
+ <TAB>
+ `minibuffer-complete'
+
+ with other characters bound as in `minibuffer-local-map' (*note
+ Text from Minibuffer::).
+
+ - Variable: minibuffer-local-must-match-map
+ `completing-read' uses this value as the local keymap when an
+ exact match of one of the completions is required. Therefore, no
+ keys are bound to `exit-minibuffer', the command that exits the
+ minibuffer unconditionally. By default, this keymap makes the
+ following bindings:
+
+ `?'
+ `minibuffer-completion-help'
+
+ <SPC>
+ `minibuffer-complete-word'
+
+ <TAB>
+ `minibuffer-complete'
+
+ `C-j'
+ `minibuffer-complete-and-exit'
+
+ <RET>
+ `minibuffer-complete-and-exit'
+
+ with other characters bound as in `minibuffer-local-map'.
+
+ - Variable: minibuffer-completion-table
+ The value of this variable is the alist or obarray used for
+ completion in the minibuffer. This is the global variable that
+ contains what `completing-read' passes to `try-completion'. It is
+ used by minibuffer completion commands such as
+ `minibuffer-complete-word'.
+
+ - Variable: minibuffer-completion-predicate
+ This variable's value is the predicate that `completing-read'
+ passes to `try-completion'. The variable is also used by the other
+ minibuffer completion functions.
+
+ - Command: minibuffer-complete-word
+ This function completes the minibuffer contents by at most a single
+ word. Even if the minibuffer contents have only one completion,
+ `minibuffer-complete-word' does not add any characters beyond the
+ first character that is not a word constituent. *Note Syntax
+ Tables::.
+
+ - Command: minibuffer-complete
+ This function completes the minibuffer contents as far as possible.
+
+ - Command: minibuffer-complete-and-exit
+ This function completes the minibuffer contents, and exits if
+ confirmation is not required, i.e., if
+ `minibuffer-completion-confirm' is `nil'. If confirmation _is_
+ required, it is given by repeating this command immediately--the
+ command is programmed to work without confirmation when run twice
+ in succession.
+
+ - Variable: minibuffer-completion-confirm
+ When the value of this variable is non-`nil', XEmacs asks for
+ confirmation of a completion before exiting the minibuffer. The
+ function `minibuffer-complete-and-exit' checks the value of this
+ variable before it exits.
+
+ - Command: minibuffer-completion-help
+ This function creates a list of the possible completions of the
+ current minibuffer contents. It works by calling `all-completions'
+ using the value of the variable `minibuffer-completion-table' as
+ the COLLECTION argument, and the value of
+ `minibuffer-completion-predicate' as the PREDICATE argument. The
+ list of completions is displayed as text in a buffer named
+ `*Completions*'.
+
+ - Function: display-completion-list completions &rest cl-keys
+ This function displays COMPLETIONS to the stream in
+ `standard-output', usually a buffer. (*Note Read and Print::, for
+ more information about streams.) The argument COMPLETIONS is
+ normally a list of completions just returned by `all-completions',
+ but it does not have to be. Each element may be a symbol or a
+ string, either of which is simply printed, or a list of two
+ strings, which is printed as if the strings were concatenated.
+
+ This function is called by `minibuffer-completion-help'. The most
+ common way to use it is together with
+ `with-output-to-temp-buffer', like this:
+
+ (with-output-to-temp-buffer "*Completions*"
+ (display-completion-list
+ (all-completions (buffer-string) my-alist)))
+
+ - User Option: completion-auto-help
+ If this variable is non-`nil', the completion commands
+ automatically display a list of possible completions whenever
+ nothing can be completed because the next character is not
+ uniquely determined.
+
+\1f
File: lispref.info, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion
High-Level Completion Functions
;; The user types `minibuffer.t <RET>'.
=> "minibuffer.texi"
- - Function: read-command prompt
+ - Function: read-command prompt &optinal default-value
This function reads the name of a command and returns it as a Lisp
symbol. The argument PROMPT is used as in `read-from-minibuffer'.
Recall that a command is anything for which `commandp' returns
`t', and a command name is a symbol for which `commandp' returns
`t'. *Note Interactive Call::.
+ The argument DEFAULT-VALUE specifies what to return if the user
+ enters null input. It can be a symbol or a string; if it is a
+ string, `read-command' interns it before returning it. If DEFAULT
+ is `nil', that means no default has been specified; then if the
+ user enters null input, the return value is `nil'.
+
(read-command "Command name? ")
;; After evaluation of the preceding expression,
(intern (completing-read PROMPT obarray
'commandp t nil))
- - Function: read-variable prompt
+ - Function: read-variable prompt &optional default-value
This function reads the name of a user variable and returns it as a
symbol.
+ The argument DEFAULT-VALUE specifies what to return if the user
+ enters null input. It can be a symbol or a string; if it is a
+ string, `read-variable' interns it before returning it. If DEFAULT
+ is `nil', that means no default has been specified; then if the
+ user enters null input, the return value is `nil'.
+
(read-variable "Variable name? ")
;; After evaluation of the preceding expression,
of the default directory.
- Function: read-file-name prompt &optional directory default existing
- initial
+ initial history
This function reads a file name in the minibuffer, prompting with
PROMPT and providing completion. If DEFAULT is non-`nil', then
the function returns DEFAULT if the user just types <RET>.
(three-b "*scratch*" "declarations.texi" "*mail*")
=> nil
-\1f
-File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
-
-Interactive Call
-================
-
- After the command loop has translated a key sequence into a
-definition, it invokes that definition using the function
-`command-execute'. If the definition is a function that is a command,
-`command-execute' calls `call-interactively', which reads the arguments
-and calls the command. You can also call these functions yourself.
-
- - Function: commandp object
- Returns `t' if OBJECT is suitable for calling interactively; that
- is, if OBJECT is a command. Otherwise, returns `nil'.
-
- The interactively callable objects include strings and vectors
- (treated as keyboard macros), lambda expressions that contain a
- top-level call to `interactive', compiled-function objects made
- from such lambda expressions, autoload objects that are declared
- as interactive (non-`nil' fourth argument to `autoload'), and some
- of the primitive functions.
-
- A symbol is `commandp' if its function definition is `commandp'.
-
- Keys and keymaps are not commands. Rather, they are used to look
- up commands (*note Keymaps::).
-
- See `documentation' in *Note Accessing Documentation::, for a
- realistic example of using `commandp'.
-
- - Function: call-interactively command &optional record-flag
- This function calls the interactively callable function COMMAND,
- reading arguments according to its interactive calling
- specifications. An error is signaled if COMMAND is not a function
- or if it cannot be called interactively (i.e., is not a command).
- Note that keyboard macros (strings and vectors) are not accepted,
- even though they are considered commands, because they are not
- functions.
-
- If RECORD-FLAG is the symbol `lambda', the interactive calling
- arguments for `command' are read and returned as a list, but the
- function is not called on them.
-
- If RECORD-FLAG is `t', then this command and its arguments are
- unconditionally added to the list `command-history'. Otherwise,
- the command is added only if it uses the minibuffer to read an
- argument. *Note Command History::.
-
- - Function: command-execute command &optional record-flag
- This function executes COMMAND as an editing command. The
- argument COMMAND must satisfy the `commandp' predicate; i.e., it
- must be an interactively callable function or a keyboard macro.
-
- A string or vector as COMMAND is executed with
- `execute-kbd-macro'. A function is passed to
- `call-interactively', along with the optional RECORD-FLAG.
-
- A symbol is handled by using its function definition in its place.
- A symbol with an `autoload' definition counts as a command if it
- was declared to stand for an interactively callable function.
- Such a definition is handled by loading the specified library and
- then rechecking the definition of the symbol.
-
- - Command: execute-extended-command prefix-argument
- This function reads a command name from the minibuffer using
- `completing-read' (*note Completion::). Then it uses
- `command-execute' to call the specified command. Whatever that
- command returns becomes the value of `execute-extended-command'.
-
- If the command asks for a prefix argument, it receives the value
- PREFIX-ARGUMENT. If `execute-extended-command' is called
- interactively, the current raw prefix argument is used for
- PREFIX-ARGUMENT, and thus passed on to whatever command is run.
-
- `execute-extended-command' is the normal definition of `M-x', so
- it uses the string `M-x ' as a prompt. (It would be better to
- take the prompt from the events used to invoke
- `execute-extended-command', but that is painful to implement.) A
- description of the value of the prefix argument, if any, also
- becomes part of the prompt.
-
- (execute-extended-command 1)
- ---------- Buffer: Minibuffer ----------
- 1 M-x forward-word RET
- ---------- Buffer: Minibuffer ----------
- => t
-
- - Function: interactive-p
- This function returns `t' if the containing function (the one that
- called `interactive-p') was called interactively, with the function
- `call-interactively'. (It makes no difference whether
- `call-interactively' was called from Lisp or directly from the
- editor command loop.) If the containing function was called by
- Lisp evaluation (or with `apply' or `funcall'), then it was not
- called interactively.
-
- The most common use of `interactive-p' is for deciding whether to
- print an informative message. As a special exception,
- `interactive-p' returns `nil' whenever a keyboard macro is being
- run. This is to suppress the informative messages and speed
- execution of the macro.
-
- For example:
-
- (defun foo ()
- (interactive)
- (and (interactive-p)
- (message "foo")))
- => foo
-
- (defun bar ()
- (interactive)
- (setq foobar (list (foo) (interactive-p))))
- => bar
-
- ;; Type `M-x foo'.
- -| foo
-
- ;; Type `M-x bar'.
- ;; This does not print anything.
-
- foobar
- => (nil t)
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
+
+Interactive Call
+================
+
+ After the command loop has translated a key sequence into a
+definition, it invokes that definition using the function
+`command-execute'. If the definition is a function that is a command,
+`command-execute' calls `call-interactively', which reads the arguments
+and calls the command. You can also call these functions yourself.
+
+ - Function: commandp object
+ Returns `t' if OBJECT is suitable for calling interactively; that
+ is, if OBJECT is a command. Otherwise, returns `nil'.
+
+ The interactively callable objects include strings and vectors
+ (treated as keyboard macros), lambda expressions that contain a
+ top-level call to `interactive', compiled-function objects made
+ from such lambda expressions, autoload objects that are declared
+ as interactive (non-`nil' fourth argument to `autoload'), and some
+ of the primitive functions.
+
+ A symbol is `commandp' if its function definition is `commandp'.
+
+ Keys and keymaps are not commands. Rather, they are used to look
+ up commands (*note Keymaps::).
+
+ See `documentation' in *Note Accessing Documentation::, for a
+ realistic example of using `commandp'.
+
+ - Function: call-interactively command &optional record-flag
+ This function calls the interactively callable function COMMAND,
+ reading arguments according to its interactive calling
+ specifications. An error is signaled if COMMAND is not a function
+ or if it cannot be called interactively (i.e., is not a command).
+ Note that keyboard macros (strings and vectors) are not accepted,
+ even though they are considered commands, because they are not
+ functions.
+
+ If RECORD-FLAG is the symbol `lambda', the interactive calling
+ arguments for `command' are read and returned as a list, but the
+ function is not called on them.
+
+ If RECORD-FLAG is `t', then this command and its arguments are
+ unconditionally added to the list `command-history'. Otherwise,
+ the command is added only if it uses the minibuffer to read an
+ argument. *Note Command History::.
+
+ - Function: command-execute command &optional record-flag
+ This function executes COMMAND as an editing command. The
+ argument COMMAND must satisfy the `commandp' predicate; i.e., it
+ must be an interactively callable function or a keyboard macro.
+
+ A string or vector as COMMAND is executed with
+ `execute-kbd-macro'. A function is passed to
+ `call-interactively', along with the optional RECORD-FLAG.
+
+ A symbol is handled by using its function definition in its place.
+ A symbol with an `autoload' definition counts as a command if it
+ was declared to stand for an interactively callable function.
+ Such a definition is handled by loading the specified library and
+ then rechecking the definition of the symbol.
+
+ - Command: execute-extended-command prefix-argument
+ This function reads a command name from the minibuffer using
+ `completing-read' (*note Completion::). Then it uses
+ `command-execute' to call the specified command. Whatever that
+ command returns becomes the value of `execute-extended-command'.
+
+ If the command asks for a prefix argument, it receives the value
+ PREFIX-ARGUMENT. If `execute-extended-command' is called
+ interactively, the current raw prefix argument is used for
+ PREFIX-ARGUMENT, and thus passed on to whatever command is run.
+
+ `execute-extended-command' is the normal definition of `M-x', so
+ it uses the string `M-x ' as a prompt. (It would be better to
+ take the prompt from the events used to invoke
+ `execute-extended-command', but that is painful to implement.) A
+ description of the value of the prefix argument, if any, also
+ becomes part of the prompt.
+
+ (execute-extended-command 1)
+ ---------- Buffer: Minibuffer ----------
+ 1 M-x forward-word RET
+ ---------- Buffer: Minibuffer ----------
+ => t
+
+ - Function: interactive-p
+ This function returns `t' if the containing function (the one that
+ called `interactive-p') was called interactively, with the function
+ `call-interactively'. (It makes no difference whether
+ `call-interactively' was called from Lisp or directly from the
+ editor command loop.) If the containing function was called by
+ Lisp evaluation (or with `apply' or `funcall'), then it was not
+ called interactively.
+
+ The most common use of `interactive-p' is for deciding whether to
+ print an informative message. As a special exception,
+ `interactive-p' returns `nil' whenever a keyboard macro is being
+ run. This is to suppress the informative messages and speed
+ execution of the macro.
+
+ For example:
+
+ (defun foo ()
+ (interactive)
+ (and (interactive-p)
+ (message "foo")))
+ => foo
+
+ (defun bar ()
+ (interactive)
+ (setq foobar (list (foo) (interactive-p))))
+ => bar
+
+ ;; Type `M-x foo'.
+ -| foo
+
+ ;; Type `M-x bar'.
+ ;; This does not print anything.
+
+ foobar
+ => (nil t)
+
+\1f
File: lispref.info, Node: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop
Information from the Command Loop
(discard-input))
=> nil
-\1f
-File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop
-
-Waiting for Elapsed Time or Input
-=================================
-
- The wait functions are designed to wait for a certain amount of time
-to pass or until there is input. For example, you may wish to pause in
-the middle of a computation to allow the user time to view the display.
-`sit-for' pauses and updates the screen, and returns immediately if
-input comes in, while `sleep-for' pauses without updating the screen.
-
- Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
-two arguments to specify the time (one integer and one float value),
-instead of a single argument that can be either an integer or a float.
-
- - Function: sit-for seconds &optional nodisp
- This function performs redisplay (provided there is no pending
- input from the user), then waits SECONDS seconds, or until input is
- available. The result is `t' if `sit-for' waited the full time
- with no input arriving (see `input-pending-p' in *Note Peeking and
- Discarding::). Otherwise, the value is `nil'.
-
- The argument SECONDS need not be an integer. If it is a floating
- point number, `sit-for' waits for a fractional number of seconds.
-
- Redisplay is normally preempted if input arrives, and does not
- happen at all if input is available before it starts. (You can
- force screen updating in such a case by using `force-redisplay'.
- *Note Refresh Screen::.) If there is no input pending, you can
- force an update with no delay by using `(sit-for 0)'.
-
- If NODISP is non-`nil', then `sit-for' does not redisplay, but it
- still returns as soon as input is available (or when the timeout
- elapses).
-
- The usual purpose of `sit-for' is to give the user time to read
- text that you display.
-
- - Function: sleep-for seconds
- This function simply pauses for SECONDS seconds without updating
- the display. This function pays no attention to available input.
- It returns `nil'.
-
- The argument SECONDS need not be an integer. If it is a floating
- point number, `sleep-for' waits for a fractional number of seconds.
-
- Use `sleep-for' when you wish to guarantee a delay.
-
- *Note Time of Day::, for functions to get the current time.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop
+
+Waiting for Elapsed Time or Input
+=================================
+
+ The wait functions are designed to wait for a certain amount of time
+to pass or until there is input. For example, you may wish to pause in
+the middle of a computation to allow the user time to view the display.
+`sit-for' pauses and updates the screen, and returns immediately if
+input comes in, while `sleep-for' pauses without updating the screen.
+
+ Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
+two arguments to specify the time (one integer and one float value),
+instead of a single argument that can be either an integer or a float.
+
+ - Function: sit-for seconds &optional nodisp
+ This function performs redisplay (provided there is no pending
+ input from the user), then waits SECONDS seconds, or until input is
+ available. The result is `t' if `sit-for' waited the full time
+ with no input arriving (see `input-pending-p' in *Note Peeking and
+ Discarding::). Otherwise, the value is `nil'.
+
+ The argument SECONDS need not be an integer. If it is a floating
+ point number, `sit-for' waits for a fractional number of seconds.
+
+ Redisplay is normally preempted if input arrives, and does not
+ happen at all if input is available before it starts. (You can
+ force screen updating in such a case by using `force-redisplay'.
+ *Note Refresh Screen::.) If there is no input pending, you can
+ force an update with no delay by using `(sit-for 0)'.
+
+ If NODISP is non-`nil', then `sit-for' does not redisplay, but it
+ still returns as soon as input is available (or when the timeout
+ elapses).
+
+ The usual purpose of `sit-for' is to give the user time to read
+ text that you display.
+
+ - Function: sleep-for seconds
+ This function simply pauses for SECONDS seconds without updating
+ the display. This function pays no attention to available input.
+ It returns `nil'.
+
+ The argument SECONDS need not be an integer. If it is a floating
+ point number, `sleep-for' waits for a fractional number of seconds.
+
+ Use `sleep-for' when you wish to guarantee a delay.
+
+ *Note Time of Day::, for functions to get the current time.
+
+\1f
File: lispref.info, Node: Quitting, Next: Prefix Command Arguments, Prev: Waiting, Up: Command Loop
Quitting
using a dialog box.
\1f
-File: lispref.info, Node: Toolbar, Next: Scrollbars, Prev: Dialog Boxes, Up: Top
+File: lispref.info, Node: Toolbar, Next: Gutter, Prev: Dialog Boxes, Up: Top
Toolbar
*******
startup.
\1f
-File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Toolbar, Up: Top
+File: lispref.info, Node: Gutter, Next: Scrollbars, Prev: Toolbar, Up: Top
-scrollbars
+Gutter
+******
+
+ A gutter is a rectangle displayed along one edge of a frame. It can
+contain arbitrary text or graphics.
+
+* Menu:
+
+* Gutter Intro:: An introduction.
+* Gutter Descriptor Format:: How to create a gutter.
+* Specifying a Gutter:: Setting a gutter's contents.
+* Other Gutter Variables:: Controlling the size of gutters.
+* Common Gutter Widgets:: Things to put in gutters.
+
+\1f
+File: lispref.info, Node: Gutter Intro, Next: Gutter Descriptor Format, Up: Gutter
+
+Gutter Intro
+============
+
+ A "gutter" is a rectangle displayed along one edge of a frame. It
+can contain arbitrary text or graphics. It could be considered a
+generalization of a toolbar, although toolbars are not currently
+implemented using gutters.
+
+ In XEmacs, a gutter can be displayed along any of the four edges of
+the frame, and two or more different edges can be displaying gutters
+simultaneously. The contents, thickness, and visibility of the gutters
+can be controlled separately, and the values can be per-buffer,
+per-frame, etc., using specifiers (*note Specifiers::).
+
+ Normally, there is one gutter displayed in a frame. Usually, this is
+the default gutter, containing buffer tabs, but modes cab override this
+and substitute their own gutter. This default gutter is usually
+positioned along the top of the frame, but this can be changed using
+`set-default-gutter-position'.
+
+ Note that, for each of the gutter properties (contents, thickness,
+and visibility), there is a separate specifier for each of the four
+gutter positions (top, bottom, left, and right), and an additional
+specifier for the "default" gutter, i.e. the gutter whose position is
+controlled by `set-default-gutter-position'. The way this works is
+that `set-default-gutter-position' arranges things so that the
+appropriate position-specific specifiers for the default position
+inherit from the corresponding default specifiers. That way, if the
+position-specific specifier does not give a value (which it usually
+doesn't), then the value from the default specifier applies. If you
+want to control the default gutter, you just change the default
+specifiers, and everything works. A package such as VM that wants to
+put its own gutter in a different location from the default just sets
+the position-specific specifiers, and if the user sets the default
+gutter to the same position, it will just not be visible.
+
+\1f
+File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Gutter Intro, Up: Gutter
+
+Gutter Descriptor Format
+========================
+
+ The contents of a gutter are specified using a "gutter descriptor".
+The format of a gutter descriptor is a list of "gutter button
+descriptors". Each gutter button descriptor is a vector in one of the
+following formats:
+
+ * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
+
+ * `[:style 2D-OR-3D]'
+
+ * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
+
+ * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
+
+ Optionally, one of the gutter button descriptors may be `nil'
+instead of a vector; this signifies the division between the gutter
+buttons that are to be displayed flush-left, and the buttons to be
+displayed flush-right.
+
+ The first vector format above specifies a normal gutter button; the
+others specify blank areas in the gutter.
+
+ For the first vector format:
+
+ * GLYPH-LIST should be a list of one to six glyphs (as created by
+ `make-glyph') or a symbol whose value is such a list. The first
+ glyph, which must be provided, is the glyph used to display the
+ gutter button when it is in the "up" (not pressed) state. The
+ optional second glyph is for displaying the button when it is in
+ the "down" (pressed) state. The optional third glyph is for when
+ the button is disabled. The last three glyphs are for displaying
+ the button in the "up", "down", and "disabled" states,
+ respectively, but are used when the user has called for captioned
+ gutter buttons (using `gutter-buttons-captioned-p'). The function
+ `gutter-make-button-list' is useful in creating these glyph lists.
+
+ * Even if you do not provide separate down-state and disabled-state
+ glyphs, the user will still get visual feedback to indicate which
+ state the button is in. Buttons in the up-state are displayed
+ with a shadowed border that gives a raised appearance to the
+ button. Buttons in the down-state are displayed with shadows that
+ give a recessed appearance. Buttons in the disabled state are
+ displayed with no shadows, giving a 2-d effect.
+
+ * If some of the gutter glyphs are not provided, they inherit as
+ follows:
+
+ UP: up
+ DOWN: down -> up
+ DISABLED: disabled -> up
+ CAP-UP: cap-up -> up
+ CAP-DOWN: cap-down -> cap-up -> down -> up
+ CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
+
+ * The second element FUNCTION is a function to be called when the
+ gutter button is activated (i.e. when the mouse is released over
+ the gutter button, if the press occurred in the gutter). It can
+ be any form accepted by `call-interactively', since this is how it
+ is invoked.
+
+ * The third element ENABLED-P specifies whether the gutter button is
+ enabled (disabled buttons do nothing when they are activated, and
+ are displayed differently; see above). It should be either a
+ boolean or a form that evaluates to a boolean.
+
+ * The fourth element HELP, if non-`nil', should be a string. This
+ string is displayed in the echo area when the mouse passes over the
+ gutter button.
+
+ For the other vector formats (specifying blank areas of the gutter):
+
+ * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
+ whether the area is displayed with shadows (giving it a raised,
+ 3-d appearance) or without shadows (giving it a flat appearance).
+
+ * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
+ area. If omitted, it defaults to a device-specific value (8
+ pixels for X devices).
+
+ - Function: gutter-make-button-list up &optional down disabled cap-up
+ cap-down cap-disabled
+ This function calls `make-glyph' on each arg and returns a list of
+ the results. This is useful for setting the first argument of a
+ gutter button descriptor (typically, the result of this function
+ is assigned to a symbol, which is specified as the first argument
+ of the gutter button descriptor).
+
+ - Function: check-gutter-button-syntax button &optional noerror
+ Verify the syntax of entry BUTTON in a gutter description list.
+ If you want to verify the syntax of a gutter description list as a
+ whole, use `check-valid-instantiator' with a specifier type of
+ `gutter'.
+
+\1f
+File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter
+
+Specifying a Gutter
+===================
+
+ In order to specify the contents of a gutter, set one of the
+specifier variables `default-gutter', `top-gutter', `bottom-gutter',
+`left-gutter', or `right-gutter'. These are specifiers, which means
+you set them with `set-specifier' and query them with `specifier-specs'
+or `specifier-instance'. You will get an error if you try to set them
+using `setq'. The valid instantiators for these specifiers are gutter
+descriptors, as described above. *Note Specifiers::, for more
+information.
+
+ Most of the time, you will set `default-gutter', which allows the
+user to choose where the gutter should go.
+
+ - Specifier: default-gutter
+ The position of this gutter is specified in the function
+ `default-gutter-position'. If the corresponding position-specific
+ gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
+ does not specify a gutter in a particular domain, then the value
+ of `default-gutter' in that domain, of any, will be used instead.
+
+ Note that the gutter at any particular position will not be displayed
+unless its thickness (width or height, depending on orientation) is
+non-zero and its visibility status is true. The thickness is controlled
+by the specifiers `top-gutter-height', `bottom-gutter-height',
+`left-gutter-width', and `right-gutter-width', and the visibility
+status is controlled by the specifiers `top-gutter-visible-p',
+`bottom-gutter-visible-p', `left-gutter-visible-p', and
+`right-gutter-visible-p' (*note Other Gutter Variables::).
+
+ - Function: set-default-gutter-position position
+ This function sets the position that the `default-gutter' will be
+ displayed at. Valid positions are the symbols `top', `bottom',
+ `left' and `right'. What this actually does is set the fallback
+ specifier for the position-specific specifier corresponding to the
+ given position to `default-gutter', and set the fallbacks for the
+ other position-specific specifiers to `nil'. It also does the
+ same thing for the position-specific thickness and visibility
+ specifiers, which inherit from one of `default-gutter-height' or
+ `default-gutter-width', and from `default-gutter-visible-p',
+ respectively (*note Other Gutter Variables::).
+
+ - Function: default-gutter-position
+ This function returns the position that the `default-gutter' will
+ be displayed at.
+
+ You can also explicitly set a gutter at a particular position. When
+redisplay determines what to display at a particular position in a
+particular domain (i.e. window), it first consults the position-specific
+gutter. If that does not yield a gutter descriptor, the
+`default-gutter' is consulted if `default-gutter-position' indicates
+this position.
+
+ - Specifier: top-gutter
+ Specifier for the gutter at the top of the frame.
+
+ - Specifier: bottom-gutter
+ Specifier for the gutter at the bottom of the frame.
+
+ - Specifier: left-gutter
+ Specifier for the gutter at the left edge of the frame.
+
+ - Specifier: right-gutter
+ Specifier for the gutter at the right edge of the frame.
+
+ - Function: gutter-specifier-p object
+ This function returns non-nil if OBJECT is a gutter specifier.
+ Gutter specifiers are the actual objects contained in the gutter
+ variables described above, and their valid instantiators are
+ gutter descriptors (*note Gutter Descriptor Format::).
+
+\1f
+File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter
+
+Other Gutter Variables
+======================
+
+ The variables to control the gutter thickness, visibility status, and
+captioned status are all specifiers. *Note Specifiers::.
+
+ - Specifier: default-gutter-height
+ This specifies the height of the default gutter, if it's oriented
+ horizontally. The position of the default gutter is specified by
+ the function `set-default-gutter-position'. If the corresponding
+ position-specific gutter thickness specifier (e.g.
+ `top-gutter-height' if `default-gutter-position' is `top') does
+ not specify a thickness in a particular domain (a window or a
+ frame), then the value of `default-gutter-height' or
+ `default-gutter-width' (depending on the gutter orientation) in
+ that domain, if any, will be used instead.
+
+ - Specifier: default-gutter-width
+ This specifies the width of the default gutter, if it's oriented
+ vertically. This behaves like `default-gutter-height'.
+
+ Note that `default-gutter-height' is only used when
+`default-gutter-position' is `top' or `bottom', and
+`default-gutter-width' is only used when `default-gutter-position' is
+`left' or `right'.
+
+ - Specifier: top-gutter-height
+ This specifies the height of the top gutter.
+
+ - Specifier: bottom-gutter-height
+ This specifies the height of the bottom gutter.
+
+ - Specifier: left-gutter-width
+ This specifies the width of the left gutter.
+
+ - Specifier: right-gutter-width
+ This specifies the width of the right gutter.
+
+ Note that all of the position-specific gutter thickness specifiers
+have a fallback value of zero when they do not correspond to the
+default gutter. Therefore, you will have to set a non-zero thickness
+value if you want a position-specific gutter to be displayed.
+
+ - Specifier: default-gutter-visible-p
+ This specifies whether the default gutter is visible. The
+ position of the default gutter is specified by the function
+ `set-default-gutter-position'. If the corresponding
+ position-specific gutter visibility specifier (e.g.
+ `top-gutter-visible-p' if `default-gutter-position' is `top') does
+ not specify a visible-p value in a particular domain (a window or
+ a frame), then the value of `default-gutter-visible-p' in that
+ domain, if any, will be used instead.
+
+ - Specifier: top-gutter-visible-p
+ This specifies whether the top gutter is visible.
+
+ - Specifier: bottom-gutter-visible-p
+ This specifies whether the bottom gutter is visible.
+
+ - Specifier: left-gutter-visible-p
+ This specifies whether the left gutter is visible.
+
+ - Specifier: right-gutter-visible-p
+ This specifies whether the right gutter is visible.
+
+ `default-gutter-visible-p' and all of the position-specific gutter
+visibility specifiers have a fallback value of true.
+
+ Internally, gutter thickness and visibility specifiers are
+instantiated in both window and frame domains, for different purposes.
+The value in the domain of a frame's selected window specifies the
+actual gutter thickness or visibility that you will see in that frame.
+The value in the domain of a frame itself specifies the gutter
+thickness or visibility that is used in frame geometry calculations.
+
+ Thus, for example, if you set the frame width to 80 characters and
+the left gutter width for that frame to 68 pixels, then the frame will
+be sized to fit 80 characters plus a 68-pixel left gutter. If you then
+set the left gutter width to 0 for a particular buffer (or if that
+buffer does not specify a left gutter or has a nil value specified for
+`left-gutter-visible-p'), you will find that, when that buffer is
+displayed in the selected window, the window will have a width of 86 or
+87 characters - the frame is sized for a 68-pixel left gutter but the
+selected window specifies that the left gutter is not visible, so it is
+expanded to take up the slack.
+
+ - Specifier: gutter-buttons-captioned-p
+ Whether gutter buttons are captioned. This affects which glyphs
+ from a gutter button descriptor are chosen. *Note Gutter
+ Descriptor Format::.
+
+ You can also reset the gutter to what it was when XEmacs started up.
+
+ - Constant: initial-gutter-spec
+ The gutter descriptor used to initialize `default-gutter' at
+ startup.
+
+\1f
+File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter
+
+Common Gutter Widgets
+=====================
+
+ A gutter can contain arbitrary text. So, for example, in an Info
+buffer you could put the title of the current node in the top gutter,
+and it would not scroll out of view in a long node. (This is an
+artificial example, since usually the node name is sufficiently
+descriptive, and Info puts that in the mode line.)
+
+ A more common use for the gutter is to hold some kind of active
+widget. The buffer-tab facility, available in all XEmacs frames,
+creates an array of file-folder-like tabs, which the user can click with
+the mouse to switch buffers. W3 uses a progress-bar widget in the
+bottom gutter to give a visual indication of the progress of
+time-consuming operations like downloading.
+
+* Menu:
+
+* Buffer Tabs:: Tabbed divider index metaphor for switching buffers.
+* Progress Bars:: Visual indication of operation progress.
+
+\1f
+File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets
+
+Buffer Tabs
+===========
+
+ Not documented yet.
+
+\1f
+File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
+
+Progress Bars
+=============
+
+ Not documented yet.
+
+\1f
+File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top
+
+Scrollbars
**********
Not yet documented.
* 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.
-
Foundation instead of in the original English.
\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 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.
-
Foundation instead of in the original English.
\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.
+
+\1f
File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
Substituting Key Bindings in Documentation
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.
-
Foundation instead of in the original English.
\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.
+
+\1f
File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
Other Information about Files
`delete-file' does not work for files that are directories; you
must use `delete-directory' in that case.
-\1f
-File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
-
-Making Certain File Names "Magic"
-=================================
-
- You can implement special handling for certain file names. This is
-called making those names "magic". You must supply a regular
-expression to define the class of names (all those that match the
-regular expression), plus a handler that implements all the primitive
-XEmacs file operations for file names that do match.
-
- The variable `file-name-handler-alist' holds a list of handlers,
-together with regular expressions that determine when to apply each
-handler. Each element has this form:
-
- (REGEXP . HANDLER)
-
-All the XEmacs primitives for file access and file name transformation
-check the given file name against `file-name-handler-alist'. If the
-file name matches REGEXP, the primitives handle that file by calling
-HANDLER.
-
- The first argument given to HANDLER is the name of the primitive;
-the remaining arguments are the arguments that were passed to that
-operation. (The first of these arguments is typically the file name
-itself.) For example, if you do this:
-
- (file-exists-p FILENAME)
-
-and FILENAME has handler HANDLER, then HANDLER is called like this:
-
- (funcall HANDLER 'file-exists-p FILENAME)
-
- Here are the operations that a magic file name handler gets to
-handle:
-
-`add-name-to-file', `copy-file', `delete-directory', `delete-file',
-`diff-latest-backup-file', `directory-file-name', `directory-files',
-`dired-compress-file', `dired-uncache', `expand-file-name',
-`file-accessible-directory-p', `file-attributes', `file-directory-p',
-`file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
-`file-name-all-completions', `file-name-as-directory',
-`file-name-completion', `file-name-directory', `file-name-nondirectory',
-`file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
-`file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
-`get-file-buffer', `insert-directory', `insert-file-contents', `load',
-`make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
-`set-visited-file-modtime', `unhandled-file-name-directory',
-`verify-visited-file-modtime', `write-region'.
-
- Handlers for `insert-file-contents' typically need to clear the
-buffer's modified flag, with `(set-buffer-modified-p nil)', if the
-VISIT argument is non-`nil'. This also has the effect of unlocking the
-buffer if it is locked.
-
- The handler function must handle all of the above operations, and
-possibly others to be added in the future. It need not implement all
-these operations itself--when it has nothing special to do for a
-certain operation, it can reinvoke the primitive, to handle the
-operation "in the usual way". It should always reinvoke the primitive
-for an operation it does not recognize. Here's one way to do this:
-
- (defun my-file-handler (operation &rest args)
- ;; First check for the specific operations
- ;; that we have special handling for.
- (cond ((eq operation 'insert-file-contents) ...)
- ((eq operation 'write-region) ...)
- ...
- ;; Handle any operation we don't know about.
- (t (let ((inhibit-file-name-handlers
- (cons 'my-file-handler
- (and (eq inhibit-file-name-operation operation)
- inhibit-file-name-handlers)))
- (inhibit-file-name-operation operation))
- (apply operation args)))))
-
- When a handler function decides to call the ordinary Emacs primitive
-for the operation at hand, it needs to prevent the primitive from
-calling the same handler once again, thus leading to an infinite
-recursion. The example above shows how to do this, with the variables
-`inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
-careful to use them exactly as shown above; the details are crucial for
-proper behavior in the case of multiple handlers, and for operations
-that have two file names that may each have handlers.
-
- - Variable: inhibit-file-name-handlers
- This variable holds a list of handlers whose use is presently
- inhibited for a certain operation.
-
- - Variable: inhibit-file-name-operation
- The operation for which certain handlers are presently inhibited.
-
- - Function: find-file-name-handler file operation
- This function returns the handler function for file name FILE, or
- `nil' if there is none. The argument OPERATION should be the
- operation to be performed on the file--the value you will pass to
- the handler as its first argument when you call it. The operation
- is needed for comparison with `inhibit-file-name-operation'.
-
- - Function: file-local-copy filename
- This function copies file FILENAME to an ordinary non-magic file,
- if it isn't one already.
-
- If FILENAME specifies a "magic" file name, which programs outside
- Emacs cannot directly read or write, this copies the contents to
- an ordinary file and returns that file's name.
-
- If FILENAME is an ordinary file name, not magic, then this function
- does nothing and returns `nil'.
-
- - Function: unhandled-file-name-directory filename
- This function returns the name of a directory that is not magic.
- It uses the directory part of FILENAME if that is not magic.
- Otherwise, it asks the handler what to do.
-
- This is useful for running a subprocess; every subprocess must
- have a non-magic directory to serve as its current directory, and
- this function is a good way to come up with one.
-
-\1f
-File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
-
-Partial Files
-=============
-
-* Menu:
-
-* Intro to Partial Files::
-* Creating a Partial File::
-* Detached Partial Files::
-
-\1f
-File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
-
-Intro to Partial Files
-----------------------
-
- A "partial file" is a section of a buffer (called the "master
-buffer") that is placed in its own buffer and treated as its own file.
-Changes made to the partial file are not reflected in the master buffer
-until the partial file is "saved" using the standard buffer save
-commands. Partial files can be "reverted" (from the master buffer)
-just like normal files. When a file part is active on a master buffer,
-that section of the master buffer is marked as read-only. Two file
-parts on the same master buffer are not allowed to overlap. Partial
-file buffers are indicated by the words `File Part' in the modeline.
-
- The master buffer knows about all the partial files that are active
-on it, and thus killing or reverting the master buffer will be handled
-properly. When the master buffer is saved, if there are any unsaved
-partial files active on it then the user will be given the opportunity
-to first save these files.
-
- When a partial file buffer is first modified, the master buffer is
-automatically marked as modified so that saving the master buffer will
-work correctly.
-
-\1f
-File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
-
-Creating a Partial File
------------------------
-
- - Function: make-file-part &optional start end name buffer
- Make a file part on buffer BUFFER out of the region. Call it
- NAME. This command creates a new buffer containing the contents
- of the region and marks the buffer as referring to the specified
- buffer, called the "master buffer". When the file-part buffer is
- saved, its changes are integrated back into the master buffer.
- When the master buffer is deleted, all file parts are deleted with
- it.
-
- When called from a function, expects four arguments, START, END,
- NAME, and BUFFER, all of which are optional and default to the
- beginning of BUFFER, the end of BUFFER, a name generated from
- BUFFER name, and the current buffer, respectively.
-
-\1f
-File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
-
-Detached Partial Files
-----------------------
-
- Every partial file has an extent in the master buffer associated
-with it (called the "master extent"), marking where in the master
-buffer the partial file begins and ends. If the text in master buffer
-that is contained by the extent is deleted, then the extent becomes
-"detached", meaning that it no longer refers to a specific region of
-the master buffer. This can happen either when the text is deleted
-directly or when the master buffer is reverted. Neither of these should
-happen in normal usage because the master buffer should generally not be
-edited directly.
-
- Before doing any operation that references a partial file's master
-extent, XEmacs checks to make sure that the extent is not detached. If
-this is the case, XEmacs warns the user of this and the master extent is
-deleted out of the master buffer, disconnecting the file part. The file
-part's filename is cleared and thus must be explicitly specified if the
-detached file part is to be saved.
-
-\1f
-File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
-
-File Format Conversion
-======================
-
- The variable `format-alist' defines a list of "file formats", which
-describe textual representations used in files for the data (text,
-text-properties, and possibly other information) in an Emacs buffer.
-Emacs performs format conversion if appropriate when reading and writing
-files.
-
- - Variable: format-alist
- This list contains one format definition for each defined file
- format.
-
- Each format definition is a list of this form:
-
- (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
-
- Here is what the elements in a format definition mean:
-
-NAME
- The name of this format.
-
-DOC-STRING
- A documentation string for the format.
-
-REGEXP
- A regular expression which is used to recognize files represented
- in this format.
-
-FROM-FN
- A function to call to decode data in this format (to convert file
- data into the usual Emacs data representation).
-
- The FROM-FN is called with two args, BEGIN and END, which specify
- the part of the buffer it should convert. It should convert the
- text by editing it in place. Since this can change the length of
- the text, FROM-FN should return the modified end position.
-
- One responsibility of FROM-FN is to make sure that the beginning
- of the file no longer matches REGEXP. Otherwise it is likely to
- get called again.
-
-TO-FN
- A function to call to encode data in this format (to convert the
- usual Emacs data representation into this format).
-
- The TO-FN is called with two args, BEGIN and END, which specify
- the part of the buffer it should convert. There are two ways it
- can do the conversion:
-
- * By editing the buffer in place. In this case, TO-FN should
- return the end-position of the range of text, as modified.
-
- * By returning a list of annotations. This is a list of
- elements of the form `(POSITION . STRING)', where POSITION is
- an integer specifying the relative position in the text to be
- written, and STRING is the annotation to add there. The list
- must be sorted in order of position when TO-FN returns it.
-
- When `write-region' actually writes the text from the buffer
- to the file, it intermixes the specified annotations at the
- corresponding positions. All this takes place without
- modifying the buffer.
-
-MODIFY
- A flag, `t' if the encoding function modifies the buffer, and
- `nil' if it works by returning a list of annotations.
-
-MODE
- A mode function to call after visiting a file converted from this
- format.
-
- The function `insert-file-contents' automatically recognizes file
-formats when it reads the specified file. It checks the text of the
-beginning of the file against the regular expressions of the format
-definitions, and if it finds a match, it calls the decoding function for
-that format. Then it checks all the known formats over again. It
-keeps checking them until none of them is applicable.
-
- Visiting a file, with `find-file-noselect' or the commands that use
-it, performs conversion likewise (because it calls
-`insert-file-contents'); it also calls the mode function for each
-format that it decodes. It stores a list of the format names in the
-buffer-local variable `buffer-file-format'.
-
- - Variable: buffer-file-format
- This variable states the format of the visited file. More
- precisely, this is a list of the file format names that were
- decoded in the course of visiting the current buffer's file. It
- is always local in all buffers.
-
- When `write-region' writes data into a file, it first calls the
-encoding functions for the formats listed in `buffer-file-format', in
-the order of appearance in the list.
-
- - Function: format-write-file file format
- This command writes the current buffer contents into the file FILE
- in format FORMAT, and makes that format the default for future
- saves of the buffer. The argument FORMAT is a list of format
- names.
-
- - Function: format-find-file file format
- This command finds the file FILE, converting it according to
- format FORMAT. It also makes FORMAT the default if the buffer is
- saved later.
-
- The argument FORMAT is a list of format names. If FORMAT is
- `nil', no conversion takes place. Interactively, typing just
- <RET> for FORMAT specifies `nil'.
-
- - Function: format-insert-file file format &optional beg end
- This command inserts the contents of file FILE, converting it
- according to format FORMAT. If BEG and END are non-`nil', they
- specify which part of the file to read, as in
- `insert-file-contents' (*note Reading from Files::).
-
- The return value is like what `insert-file-contents' returns: a
- list of the absolute file name and the length of the data inserted
- (after conversion).
-
- The argument FORMAT is a list of format names. If FORMAT is
- `nil', no conversion takes place. Interactively, typing just
- <RET> for FORMAT specifies `nil'.
-
- - Function: format-find-file file format
- This command finds the file FILE, converting it according to
- format FORMAT. It also makes FORMAT the default if the buffer is
- saved later.
-
- The argument FORMAT is a list of format names. If FORMAT is
- `nil', no conversion takes place. Interactively, typing just
- <RET> for FORMAT specifies `nil'.
-
- - Function: format-insert-file file format &optional beg end
- This command inserts the contents of file FILE, converting it
- according to format FORMAT. If BEG and END are non-`nil', they
- specify which part of the file to read, as in
- `insert-file-contents' (*note Reading from Files::).
-
- The return value is like what `insert-file-contents' returns: a
- list of the absolute file name and the length of the data inserted
- (after conversion).
-
- The argument FORMAT is a list of format names. If FORMAT is
- `nil', no conversion takes place. Interactively, typing just
- <RET> for FORMAT specifies `nil'.
-
- - Variable: auto-save-file-format
- This variable specifies the format to use for auto-saving. Its
- value is a list of format names, just like the value of
- `buffer-file-format'; but it is used instead of
- `buffer-file-format' for writing auto-save files. This variable
- is always local in all buffers.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
+
+Making Certain File Names "Magic"
+=================================
+
+ You can implement special handling for certain file names. This is
+called making those names "magic". You must supply a regular
+expression to define the class of names (all those that match the
+regular expression), plus a handler that implements all the primitive
+XEmacs file operations for file names that do match.
+
+ The variable `file-name-handler-alist' holds a list of handlers,
+together with regular expressions that determine when to apply each
+handler. Each element has this form:
+
+ (REGEXP . HANDLER)
+
+All the XEmacs primitives for file access and file name transformation
+check the given file name against `file-name-handler-alist'. If the
+file name matches REGEXP, the primitives handle that file by calling
+HANDLER.
+
+ The first argument given to HANDLER is the name of the primitive;
+the remaining arguments are the arguments that were passed to that
+operation. (The first of these arguments is typically the file name
+itself.) For example, if you do this:
+
+ (file-exists-p FILENAME)
+
+and FILENAME has handler HANDLER, then HANDLER is called like this:
+
+ (funcall HANDLER 'file-exists-p FILENAME)
+
+ Here are the operations that a magic file name handler gets to
+handle:
+
+`add-name-to-file', `copy-file', `delete-directory', `delete-file',
+`diff-latest-backup-file', `directory-file-name', `directory-files',
+`dired-compress-file', `dired-uncache', `expand-file-name',
+`file-accessible-directory-p', `file-attributes', `file-directory-p',
+`file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
+`file-name-all-completions', `file-name-as-directory',
+`file-name-completion', `file-name-directory', `file-name-nondirectory',
+`file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
+`file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
+`get-file-buffer', `insert-directory', `insert-file-contents', `load',
+`make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
+`set-visited-file-modtime', `unhandled-file-name-directory',
+`verify-visited-file-modtime', `write-region'.
+
+ Handlers for `insert-file-contents' typically need to clear the
+buffer's modified flag, with `(set-buffer-modified-p nil)', if the
+VISIT argument is non-`nil'. This also has the effect of unlocking the
+buffer if it is locked.
+
+ The handler function must handle all of the above operations, and
+possibly others to be added in the future. It need not implement all
+these operations itself--when it has nothing special to do for a
+certain operation, it can reinvoke the primitive, to handle the
+operation "in the usual way". It should always reinvoke the primitive
+for an operation it does not recognize. Here's one way to do this:
+
+ (defun my-file-handler (operation &rest args)
+ ;; First check for the specific operations
+ ;; that we have special handling for.
+ (cond ((eq operation 'insert-file-contents) ...)
+ ((eq operation 'write-region) ...)
+ ...
+ ;; Handle any operation we don't know about.
+ (t (let ((inhibit-file-name-handlers
+ (cons 'my-file-handler
+ (and (eq inhibit-file-name-operation operation)
+ inhibit-file-name-handlers)))
+ (inhibit-file-name-operation operation))
+ (apply operation args)))))
+
+ When a handler function decides to call the ordinary Emacs primitive
+for the operation at hand, it needs to prevent the primitive from
+calling the same handler once again, thus leading to an infinite
+recursion. The example above shows how to do this, with the variables
+`inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
+careful to use them exactly as shown above; the details are crucial for
+proper behavior in the case of multiple handlers, and for operations
+that have two file names that may each have handlers.
+
+ - Variable: inhibit-file-name-handlers
+ This variable holds a list of handlers whose use is presently
+ inhibited for a certain operation.
+
+ - Variable: inhibit-file-name-operation
+ The operation for which certain handlers are presently inhibited.
+
+ - Function: find-file-name-handler file operation
+ This function returns the handler function for file name FILE, or
+ `nil' if there is none. The argument OPERATION should be the
+ operation to be performed on the file--the value you will pass to
+ the handler as its first argument when you call it. The operation
+ is needed for comparison with `inhibit-file-name-operation'.
+
+ - Function: file-local-copy filename
+ This function copies file FILENAME to an ordinary non-magic file,
+ if it isn't one already.
+
+ If FILENAME specifies a "magic" file name, which programs outside
+ Emacs cannot directly read or write, this copies the contents to
+ an ordinary file and returns that file's name.
+
+ If FILENAME is an ordinary file name, not magic, then this function
+ does nothing and returns `nil'.
+
+ - Function: unhandled-file-name-directory filename
+ This function returns the name of a directory that is not magic.
+ It uses the directory part of FILENAME if that is not magic.
+ Otherwise, it asks the handler what to do.
+
+ This is useful for running a subprocess; every subprocess must
+ have a non-magic directory to serve as its current directory, and
+ this function is a good way to come up with one.
+
+\1f
+File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
+
+Partial Files
+=============
+
+* Menu:
+
+* Intro to Partial Files::
+* Creating a Partial File::
+* Detached Partial Files::
+
+\1f
+File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
+
+Intro to Partial Files
+----------------------
+
+ A "partial file" is a section of a buffer (called the "master
+buffer") that is placed in its own buffer and treated as its own file.
+Changes made to the partial file are not reflected in the master buffer
+until the partial file is "saved" using the standard buffer save
+commands. Partial files can be "reverted" (from the master buffer)
+just like normal files. When a file part is active on a master buffer,
+that section of the master buffer is marked as read-only. Two file
+parts on the same master buffer are not allowed to overlap. Partial
+file buffers are indicated by the words `File Part' in the modeline.
+
+ The master buffer knows about all the partial files that are active
+on it, and thus killing or reverting the master buffer will be handled
+properly. When the master buffer is saved, if there are any unsaved
+partial files active on it then the user will be given the opportunity
+to first save these files.
+
+ When a partial file buffer is first modified, the master buffer is
+automatically marked as modified so that saving the master buffer will
+work correctly.
+
+\1f
+File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
+
+Creating a Partial File
+-----------------------
+
+ - Function: make-file-part &optional start end name buffer
+ Make a file part on buffer BUFFER out of the region. Call it
+ NAME. This command creates a new buffer containing the contents
+ of the region and marks the buffer as referring to the specified
+ buffer, called the "master buffer". When the file-part buffer is
+ saved, its changes are integrated back into the master buffer.
+ When the master buffer is deleted, all file parts are deleted with
+ it.
+
+ When called from a function, expects four arguments, START, END,
+ NAME, and BUFFER, all of which are optional and default to the
+ beginning of BUFFER, the end of BUFFER, a name generated from
+ BUFFER name, and the current buffer, respectively.
+
+\1f
+File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
+
+Detached Partial Files
+----------------------
+
+ Every partial file has an extent in the master buffer associated
+with it (called the "master extent"), marking where in the master
+buffer the partial file begins and ends. If the text in master buffer
+that is contained by the extent is deleted, then the extent becomes
+"detached", meaning that it no longer refers to a specific region of
+the master buffer. This can happen either when the text is deleted
+directly or when the master buffer is reverted. Neither of these should
+happen in normal usage because the master buffer should generally not be
+edited directly.
+
+ Before doing any operation that references a partial file's master
+extent, XEmacs checks to make sure that the extent is not detached. If
+this is the case, XEmacs warns the user of this and the master extent is
+deleted out of the master buffer, disconnecting the file part. The file
+part's filename is cleared and thus must be explicitly specified if the
+detached file part is to be saved.
+
+\1f
+File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
+
+File Format Conversion
+======================
+
+ The variable `format-alist' defines a list of "file formats", which
+describe textual representations used in files for the data (text,
+text-properties, and possibly other information) in an Emacs buffer.
+Emacs performs format conversion if appropriate when reading and writing
+files.
+
+ - Variable: format-alist
+ This list contains one format definition for each defined file
+ format.
+
+ Each format definition is a list of this form:
+
+ (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
+
+ Here is what the elements in a format definition mean:
+
+NAME
+ The name of this format.
+
+DOC-STRING
+ A documentation string for the format.
+
+REGEXP
+ A regular expression which is used to recognize files represented
+ in this format.
+
+FROM-FN
+ A function to call to decode data in this format (to convert file
+ data into the usual Emacs data representation).
+
+ The FROM-FN is called with two args, BEGIN and END, which specify
+ the part of the buffer it should convert. It should convert the
+ text by editing it in place. Since this can change the length of
+ the text, FROM-FN should return the modified end position.
+
+ One responsibility of FROM-FN is to make sure that the beginning
+ of the file no longer matches REGEXP. Otherwise it is likely to
+ get called again.
+
+TO-FN
+ A function to call to encode data in this format (to convert the
+ usual Emacs data representation into this format).
+
+ The TO-FN is called with two args, BEGIN and END, which specify
+ the part of the buffer it should convert. There are two ways it
+ can do the conversion:
+
+ * By editing the buffer in place. In this case, TO-FN should
+ return the end-position of the range of text, as modified.
+
+ * By returning a list of annotations. This is a list of
+ elements of the form `(POSITION . STRING)', where POSITION is
+ an integer specifying the relative position in the text to be
+ written, and STRING is the annotation to add there. The list
+ must be sorted in order of position when TO-FN returns it.
+
+ When `write-region' actually writes the text from the buffer
+ to the file, it intermixes the specified annotations at the
+ corresponding positions. All this takes place without
+ modifying the buffer.
+
+MODIFY
+ A flag, `t' if the encoding function modifies the buffer, and
+ `nil' if it works by returning a list of annotations.
+
+MODE
+ A mode function to call after visiting a file converted from this
+ format.
+
+ The function `insert-file-contents' automatically recognizes file
+formats when it reads the specified file. It checks the text of the
+beginning of the file against the regular expressions of the format
+definitions, and if it finds a match, it calls the decoding function for
+that format. Then it checks all the known formats over again. It
+keeps checking them until none of them is applicable.
+
+ Visiting a file, with `find-file-noselect' or the commands that use
+it, performs conversion likewise (because it calls
+`insert-file-contents'); it also calls the mode function for each
+format that it decodes. It stores a list of the format names in the
+buffer-local variable `buffer-file-format'.
+
+ - Variable: buffer-file-format
+ This variable states the format of the visited file. More
+ precisely, this is a list of the file format names that were
+ decoded in the course of visiting the current buffer's file. It
+ is always local in all buffers.
+
+ When `write-region' writes data into a file, it first calls the
+encoding functions for the formats listed in `buffer-file-format', in
+the order of appearance in the list.
+
+ - Function: format-write-file file format
+ This command writes the current buffer contents into the file FILE
+ in format FORMAT, and makes that format the default for future
+ saves of the buffer. The argument FORMAT is a list of format
+ names.
+
+ - Function: format-find-file file format
+ This command finds the file FILE, converting it according to
+ format FORMAT. It also makes FORMAT the default if the buffer is
+ saved later.
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-insert-file file format &optional beg end
+ This command inserts the contents of file FILE, converting it
+ according to format FORMAT. If BEG and END are non-`nil', they
+ specify which part of the file to read, as in
+ `insert-file-contents' (*note Reading from Files::).
+
+ The return value is like what `insert-file-contents' returns: a
+ list of the absolute file name and the length of the data inserted
+ (after conversion).
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-find-file file format
+ This command finds the file FILE, converting it according to
+ format FORMAT. It also makes FORMAT the default if the buffer is
+ saved later.
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-insert-file file format &optional beg end
+ This command inserts the contents of file FILE, converting it
+ according to format FORMAT. If BEG and END are non-`nil', they
+ specify which part of the file to read, as in
+ `insert-file-contents' (*note Reading from Files::).
+
+ The return value is like what `insert-file-contents' returns: a
+ list of the absolute file name and the length of the data inserted
+ (after conversion).
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Variable: auto-save-file-format
+ This variable specifies the format to use for auto-saving. Its
+ value is a list of format names, just like the value of
+ `buffer-file-format'; but it is used instead of
+ `buffer-file-format' for writing auto-save files. This variable
+ is always local in all buffers.
+
+\1f
File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
Files and MS-DOS
- Function: bufferp object
This function returns `t' if OBJECT is a buffer, `nil' otherwise.
-\1f
-File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
-
-The Current Buffer
-==================
-
- There are, in general, many buffers in an Emacs session. At any
-time, one of them is designated as the "current buffer". This is the
-buffer in which most editing takes place, because most of the primitives
-for examining or changing text in a buffer operate implicitly on the
-current buffer (*note Text::). Normally the buffer that is displayed on
-the screen in the selected window is the current buffer, but this is not
-always so: a Lisp program can designate any buffer as current
-temporarily in order to operate on its contents, without changing what
-is displayed on the screen.
-
- The way to designate a current buffer in a Lisp program is by calling
-`set-buffer'. The specified buffer remains current until a new one is
-designated.
-
- When an editing command returns to the editor command loop, the
-command loop designates the buffer displayed in the selected window as
-current, to prevent confusion: the buffer that the cursor is in when
-Emacs reads a command is the buffer that the command will apply to.
-(*Note Command Loop::.) Therefore, `set-buffer' is not the way to
-switch visibly to a different buffer so that the user can edit it. For
-this, you must use the functions described in *Note Displaying
-Buffers::.
-
- However, Lisp functions that change to a different current buffer
-should not depend on the command loop to set it back afterwards.
-Editing commands written in XEmacs Lisp can be called from other
-programs as well as from the command loop. It is convenient for the
-caller if the subroutine does not change which buffer is current
-(unless, of course, that is the subroutine's purpose). Therefore, you
-should normally use `set-buffer' within a `save-excursion' that will
-restore the current buffer when your function is done (*note
-Excursions::). Here is an example, the code for the command
-`append-to-buffer' (with the documentation string abridged):
-
- (defun append-to-buffer (buffer start end)
- "Append to specified buffer the text of the region.
- ..."
- (interactive "BAppend to buffer: \nr")
- (let ((oldbuf (current-buffer)))
- (save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
-
-This function binds a local variable to the current buffer, and then
-`save-excursion' records the values of point, the mark, and the
-original buffer. Next, `set-buffer' makes another buffer current.
-Finally, `insert-buffer-substring' copies the string from the original
-current buffer to the new current buffer.
-
- If the buffer appended to happens to be displayed in some window,
-the next redisplay will show how its text has changed. Otherwise, you
-will not see the change immediately on the screen. The buffer becomes
-current temporarily during the execution of the command, but this does
-not cause it to be displayed.
-
- If you make local bindings (with `let' or function arguments) for a
-variable that may also have buffer-local bindings, make sure that the
-same buffer is current at the beginning and at the end of the local
-binding's scope. Otherwise you might bind it in one buffer and unbind
-it in another! There are two ways to do this. In simple cases, you may
-see that nothing ever changes the current buffer within the scope of the
-binding. Otherwise, use `save-excursion' to make sure that the buffer
-current at the beginning is current again whenever the variable is
-unbound.
-
- It is not reliable to change the current buffer back with
-`set-buffer', because that won't do the job if a quit happens while the
-wrong buffer is current. Here is what _not_ to do:
-
- (let (buffer-read-only
- (obuf (current-buffer)))
- (set-buffer ...)
- ...
- (set-buffer obuf))
-
-Using `save-excursion', as shown below, handles quitting, errors, and
-`throw', as well as ordinary evaluation.
-
- (let (buffer-read-only)
- (save-excursion
- (set-buffer ...)
- ...))
-
- - Function: current-buffer
- This function returns the current buffer.
-
- (current-buffer)
- => #<buffer buffers.texi>
-
- - Function: set-buffer buffer-or-name
- This function makes BUFFER-OR-NAME the current buffer. It does
- not display the buffer in the currently selected window or in any
- other window, so the user cannot necessarily see the buffer. But
- Lisp programs can in any case work on it.
-
- This function returns the buffer identified by BUFFER-OR-NAME. An
- error is signaled if BUFFER-OR-NAME does not identify an existing
- buffer.
-
-\1f
-File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
-
-Buffer Names
-============
-
- Each buffer has a unique name, which is a string. Many of the
-functions that work on buffers accept either a buffer or a buffer name
-as an argument. Any argument called BUFFER-OR-NAME is of this sort,
-and an error is signaled if it is neither a string nor a buffer. Any
-argument called BUFFER must be an actual buffer object, not a name.
-
- Buffers that are ephemeral and generally uninteresting to the user
-have names starting with a space, so that the `list-buffers' and
-`buffer-menu' commands don't mention them. A name starting with space
-also initially disables recording undo information; see *Note Undo::.
-
- - Function: buffer-name &optional buffer
- This function returns the name of BUFFER as a string. If BUFFER
- is not supplied, it defaults to the current buffer.
-
- If `buffer-name' returns `nil', it means that BUFFER has been
- killed. *Note Killing Buffers::.
-
- (buffer-name)
- => "buffers.texi"
-
- (setq foo (get-buffer "temp"))
- => #<buffer temp>
- (kill-buffer foo)
- => nil
- (buffer-name foo)
- => nil
- foo
- => #<killed buffer>
-
- - Command: rename-buffer newname &optional unique
- This function renames the current buffer to NEWNAME. An error is
- signaled if NEWNAME is not a string, or if there is already a
- buffer with that name. The function returns `nil'.
-
- Ordinarily, `rename-buffer' signals an error if NEWNAME is already
- in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
- make a name that is not in use. Interactively, you can make
- UNIQUE non-`nil' with a numeric prefix argument.
-
- One application of this command is to rename the `*shell*' buffer
- to some other name, thus making it possible to create a second
- shell buffer under the name `*shell*'.
-
- - Function: get-buffer buffer-or-name
- This function returns the buffer specified by BUFFER-OR-NAME. If
- BUFFER-OR-NAME is a string and there is no buffer with that name,
- the value is `nil'. If BUFFER-OR-NAME is a buffer, it is returned
- as given. (That is not very useful, so the argument is usually a
- name.) For example:
-
- (setq b (get-buffer "lewis"))
- => #<buffer lewis>
- (get-buffer b)
- => #<buffer lewis>
- (get-buffer "Frazzle-nots")
- => nil
-
- See also the function `get-buffer-create' in *Note Creating
- Buffers::.
-
- - Function: generate-new-buffer-name starting-name &optional ignore
- This function returns a name that would be unique for a new
- buffer--but does not create the buffer. It starts with
- STARTING-NAME, and produces a name not currently in use for any
- buffer by appending a number inside of `<...>'.
-
- If IGNORE is given, it specifies a name that is okay to use (if it
- is in the sequence to be tried), even if a buffer with that name
- exists.
-
- See the related function `generate-new-buffer' in *Note Creating
- Buffers::.
-
-\1f
-File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
-
-Buffer File Name
-================
-
- The "buffer file name" is the name of the file that is visited in
-that buffer. When a buffer is not visiting a file, its buffer file name
-is `nil'. Most of the time, the buffer name is the same as the
-nondirectory part of the buffer file name, but the buffer file name and
-the buffer name are distinct and can be set independently. *Note
-Visiting Files::.
-
- - Function: buffer-file-name &optional buffer
- This function returns the absolute file name of the file that
- BUFFER is visiting. If BUFFER is not visiting any file,
- `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
- defaults to the current buffer.
-
- (buffer-file-name (other-buffer))
- => "/usr/user/lewis/manual/files.texi"
-
- - Variable: buffer-file-name
- This buffer-local variable contains the name of the file being
- visited in the current buffer, or `nil' if it is not visiting a
- file. It is a permanent local, unaffected by
- `kill-local-variables'.
-
- buffer-file-name
- => "/usr/user/lewis/manual/buffers.texi"
-
- It is risky to change this variable's value without doing various
- other things. See the definition of `set-visited-file-name' in
- `files.el'; some of the things done there, such as changing the
- buffer name, are not strictly necessary, but others are essential
- to avoid confusing XEmacs.
-
- - Variable: buffer-file-truename
- This buffer-local variable holds the truename of the file visited
- in the current buffer, or `nil' if no file is visited. It is a
- permanent local, unaffected by `kill-local-variables'. *Note
- Truenames::.
-
- - Variable: buffer-file-number
- This buffer-local variable holds the file number and directory
- device number of the file visited in the current buffer, or `nil'
- if no file or a nonexistent file is visited. It is a permanent
- local, unaffected by `kill-local-variables'. *Note Truenames::.
-
- The value is normally a list of the form `(FILENUM DEVNUM)'. This
- pair of numbers uniquely identifies the file among all files
- accessible on the system. See the function `file-attributes', in
- *Note File Attributes::, for more information about them.
-
- - Function: get-file-buffer filename
- This function returns the buffer visiting file FILENAME. If there
- is no such buffer, it returns `nil'. The argument FILENAME, which
- must be a string, is expanded (*note File Name Expansion::), then
- compared against the visited file names of all live buffers.
-
- (get-file-buffer "buffers.texi")
- => #<buffer buffers.texi>
-
- In unusual circumstances, there can be more than one buffer
- visiting the same file name. In such cases, this function returns
- the first such buffer in the buffer list.
-
- - Command: set-visited-file-name filename
- If FILENAME is a non-empty string, this function changes the name
- of the file visited in current buffer to FILENAME. (If the buffer
- had no visited file, this gives it one.) The _next time_ the
- buffer is saved it will go in the newly-specified file. This
- command marks the buffer as modified, since it does not (as far as
- XEmacs knows) match the contents of FILENAME, even if it matched
- the former visited file.
-
- If FILENAME is `nil' or the empty string, that stands for "no
- visited file". In this case, `set-visited-file-name' marks the
- buffer as having no visited file.
-
- When the function `set-visited-file-name' is called interactively,
- it prompts for FILENAME in the minibuffer.
-
- See also `clear-visited-file-modtime' and
- `verify-visited-file-modtime' in *Note Buffer Modification::.
-
- - Variable: list-buffers-directory
- This buffer-local variable records a string to display in a buffer
- listing in place of the visited file name, for buffers that don't
- have a visited file name. Dired buffers use this variable.
-
-\1f
-File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
-
-Buffer Modification
-===================
-
- XEmacs keeps a flag called the "modified flag" for each buffer, to
-record whether you have changed the text of the buffer. This flag is
-set to `t' whenever you alter the contents of the buffer, and cleared
-to `nil' when you save it. Thus, the flag shows whether there are
-unsaved changes. The flag value is normally shown in the modeline
-(*note Modeline Variables::), and controls saving (*note Saving
-Buffers::) and auto-saving (*note Auto-Saving::).
-
- Some Lisp programs set the flag explicitly. For example, the
-function `set-visited-file-name' sets the flag to `t', because the text
-does not match the newly-visited file, even if it is unchanged from the
-file formerly visited.
-
- The functions that modify the contents of buffers are described in
-*Note Text::.
-
- - Function: buffer-modified-p &optional buffer
- This function returns `t' if the buffer BUFFER has been modified
- since it was last read in from a file or saved, or `nil'
- otherwise. If BUFFER is not supplied, the current buffer is
- tested.
-
- - Function: set-buffer-modified-p flag
- This function marks the current buffer as modified if FLAG is
- non-`nil', or as unmodified if the flag is `nil'.
-
- Another effect of calling this function is to cause unconditional
- redisplay of the modeline for the current buffer. In fact, the
- function `redraw-modeline' works by doing this:
-
- (set-buffer-modified-p (buffer-modified-p))
-
- - Command: not-modified &optional arg
- This command marks the current buffer as unmodified, and not
- needing to be saved. (If ARG is non-`nil', the buffer is instead
- marked as modified.) Don't use this function in programs, since it
- prints a message in the echo area; use `set-buffer-modified-p'
- (above) instead.
-
- - Function: buffer-modified-tick &optional buffer
- This function returns BUFFER`s modification-count. This is a
- counter that increments every time the buffer is modified. If
- BUFFER is `nil' (or omitted), the current buffer is used.
-
-\1f
-File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
-
-Comparison of Modification Time
-===============================
-
- Suppose that you visit a file and make changes in its buffer, and
-meanwhile the file itself is changed on disk. At this point, saving the
-buffer would overwrite the changes in the file. Occasionally this may
-be what you want, but usually it would lose valuable information.
-XEmacs therefore checks the file's modification time using the functions
-described below before saving the file.
-
- - Function: verify-visited-file-modtime buffer
- This function compares what BUFFER has recorded for the
- modification time of its visited file against the actual
- modification time of the file as recorded by the operating system.
- The two should be the same unless some other process has written
- the file since XEmacs visited or saved it.
-
- The function returns `t' if the last actual modification time and
- XEmacs's recorded modification time are the same, `nil' otherwise.
-
- - Function: clear-visited-file-modtime
- This function clears out the record of the last modification time
- of the file being visited by the current buffer. As a result, the
- next attempt to save this buffer will not complain of a
- discrepancy in file modification times.
-
- This function is called in `set-visited-file-name' and other
- exceptional places where the usual test to avoid overwriting a
- changed file should not be done.
-
- - Function: visited-file-modtime
- This function returns the buffer's recorded last file modification
- time, as a list of the form `(HIGH . LOW)'. (This is the same
- format that `file-attributes' uses to return time values; see
- *Note File Attributes::.)
-
- - Function: set-visited-file-modtime &optional time
- This function updates the buffer's record of the last modification
- time of the visited file, to the value specified by TIME if TIME
- is not `nil', and otherwise to the last modification time of the
- visited file.
-
- If TIME is not `nil', it should have the form `(HIGH . LOW)' or
- `(HIGH LOW)', in either case containing two integers, each of
- which holds 16 bits of the time.
-
- This function is useful if the buffer was not read from the file
- normally, or if the file itself has been changed for some known
- benign reason.
-
- - Function: ask-user-about-supersession-threat filename
- This function is used to ask a user how to proceed after an
- attempt to modify an obsolete buffer visiting file FILENAME. An
- "obsolete buffer" is an unmodified buffer for which the associated
- file on disk is newer than the last save-time of the buffer. This
- means some other program has probably altered the file.
-
- Depending on the user's answer, the function may return normally,
- in which case the modification of the buffer proceeds, or it may
- signal a `file-supersession' error with data `(FILENAME)', in which
- case the proposed buffer modification is not allowed.
-
- This function is called automatically by XEmacs on the proper
- occasions. It exists so you can customize XEmacs by redefining it.
- See the file `userlock.el' for the standard definition.
-
- See also the file locking mechanism in *Note File Locks::.
-
-\1f
-File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
-
-Read-Only Buffers
-=================
-
- If a buffer is "read-only", then you cannot change its contents,
-although you may change your view of the contents by scrolling and
-narrowing.
-
- Read-only buffers are used in two kinds of situations:
-
- * A buffer visiting a write-protected file is normally read-only.
-
- Here, the purpose is to show the user that editing the buffer with
- the aim of saving it in the file may be futile or undesirable.
- The user who wants to change the buffer text despite this can do
- so after clearing the read-only flag with `C-x C-q'.
-
- * Modes such as Dired and Rmail make buffers read-only when altering
- the contents with the usual editing commands is probably a mistake.
-
- The special commands of these modes bind `buffer-read-only' to
- `nil' (with `let') or bind `inhibit-read-only' to `t' around the
- places where they change the text.
-
- - Variable: buffer-read-only
- This buffer-local variable specifies whether the buffer is
- read-only. The buffer is read-only if this variable is non-`nil'.
-
- - Variable: inhibit-read-only
- If this variable is non-`nil', then read-only buffers and read-only
- characters may be modified. Read-only characters in a buffer are
- those that have non-`nil' `read-only' properties (either text
- properties or extent properties). *Note Extent Properties::, for
- more information about text properties and extent properties.
-
- If `inhibit-read-only' is `t', all `read-only' character
- properties have no effect. If `inhibit-read-only' is a list, then
- `read-only' character properties have no effect if they are members
- of the list (comparison is done with `eq').
-
- - Command: toggle-read-only
- This command changes whether the current buffer is read-only. It
- is intended for interactive use; don't use it in programs. At any
- given point in a program, you should know whether you want the
- read-only flag on or off; so you can set `buffer-read-only'
- explicitly to the proper value, `t' or `nil'.
-
- - Function: barf-if-buffer-read-only
- This function signals a `buffer-read-only' error if the current
- buffer is read-only. *Note Interactive Call::, for another way to
- signal an error if the current buffer is read-only.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
+
+The Current Buffer
+==================
+
+ There are, in general, many buffers in an Emacs session. At any
+time, one of them is designated as the "current buffer". This is the
+buffer in which most editing takes place, because most of the primitives
+for examining or changing text in a buffer operate implicitly on the
+current buffer (*note Text::). Normally the buffer that is displayed on
+the screen in the selected window is the current buffer, but this is not
+always so: a Lisp program can designate any buffer as current
+temporarily in order to operate on its contents, without changing what
+is displayed on the screen.
+
+ The way to designate a current buffer in a Lisp program is by calling
+`set-buffer'. The specified buffer remains current until a new one is
+designated.
+
+ When an editing command returns to the editor command loop, the
+command loop designates the buffer displayed in the selected window as
+current, to prevent confusion: the buffer that the cursor is in when
+Emacs reads a command is the buffer that the command will apply to.
+(*Note Command Loop::.) Therefore, `set-buffer' is not the way to
+switch visibly to a different buffer so that the user can edit it. For
+this, you must use the functions described in *Note Displaying
+Buffers::.
+
+ However, Lisp functions that change to a different current buffer
+should not depend on the command loop to set it back afterwards.
+Editing commands written in XEmacs Lisp can be called from other
+programs as well as from the command loop. It is convenient for the
+caller if the subroutine does not change which buffer is current
+(unless, of course, that is the subroutine's purpose). Therefore, you
+should normally use `set-buffer' within a `save-excursion' that will
+restore the current buffer when your function is done (*note
+Excursions::). Here is an example, the code for the command
+`append-to-buffer' (with the documentation string abridged):
+
+ (defun append-to-buffer (buffer start end)
+ "Append to specified buffer the text of the region.
+ ..."
+ (interactive "BAppend to buffer: \nr")
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (set-buffer (get-buffer-create buffer))
+ (insert-buffer-substring oldbuf start end))))
+
+This function binds a local variable to the current buffer, and then
+`save-excursion' records the values of point, the mark, and the
+original buffer. Next, `set-buffer' makes another buffer current.
+Finally, `insert-buffer-substring' copies the string from the original
+current buffer to the new current buffer.
+
+ If the buffer appended to happens to be displayed in some window,
+the next redisplay will show how its text has changed. Otherwise, you
+will not see the change immediately on the screen. The buffer becomes
+current temporarily during the execution of the command, but this does
+not cause it to be displayed.
+
+ If you make local bindings (with `let' or function arguments) for a
+variable that may also have buffer-local bindings, make sure that the
+same buffer is current at the beginning and at the end of the local
+binding's scope. Otherwise you might bind it in one buffer and unbind
+it in another! There are two ways to do this. In simple cases, you may
+see that nothing ever changes the current buffer within the scope of the
+binding. Otherwise, use `save-excursion' to make sure that the buffer
+current at the beginning is current again whenever the variable is
+unbound.
+
+ It is not reliable to change the current buffer back with
+`set-buffer', because that won't do the job if a quit happens while the
+wrong buffer is current. Here is what _not_ to do:
+
+ (let (buffer-read-only
+ (obuf (current-buffer)))
+ (set-buffer ...)
+ ...
+ (set-buffer obuf))
+
+Using `save-excursion', as shown below, handles quitting, errors, and
+`throw', as well as ordinary evaluation.
+
+ (let (buffer-read-only)
+ (save-excursion
+ (set-buffer ...)
+ ...))
+
+ - Function: current-buffer
+ This function returns the current buffer.
+
+ (current-buffer)
+ => #<buffer buffers.texi>
+
+ - Function: set-buffer buffer-or-name
+ This function makes BUFFER-OR-NAME the current buffer. It does
+ not display the buffer in the currently selected window or in any
+ other window, so the user cannot necessarily see the buffer. But
+ Lisp programs can in any case work on it.
+
+ This function returns the buffer identified by BUFFER-OR-NAME. An
+ error is signaled if BUFFER-OR-NAME does not identify an existing
+ buffer.
+
+\1f
+File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
+
+Buffer Names
+============
+
+ Each buffer has a unique name, which is a string. Many of the
+functions that work on buffers accept either a buffer or a buffer name
+as an argument. Any argument called BUFFER-OR-NAME is of this sort,
+and an error is signaled if it is neither a string nor a buffer. Any
+argument called BUFFER must be an actual buffer object, not a name.
+
+ Buffers that are ephemeral and generally uninteresting to the user
+have names starting with a space, so that the `list-buffers' and
+`buffer-menu' commands don't mention them. A name starting with space
+also initially disables recording undo information; see *Note Undo::.
+
+ - Function: buffer-name &optional buffer
+ This function returns the name of BUFFER as a string. If BUFFER
+ is not supplied, it defaults to the current buffer.
+
+ If `buffer-name' returns `nil', it means that BUFFER has been
+ killed. *Note Killing Buffers::.
+
+ (buffer-name)
+ => "buffers.texi"
+
+ (setq foo (get-buffer "temp"))
+ => #<buffer temp>
+ (kill-buffer foo)
+ => nil
+ (buffer-name foo)
+ => nil
+ foo
+ => #<killed buffer>
+
+ - Command: rename-buffer newname &optional unique
+ This function renames the current buffer to NEWNAME. An error is
+ signaled if NEWNAME is not a string, or if there is already a
+ buffer with that name. The function returns `nil'.
+
+ Ordinarily, `rename-buffer' signals an error if NEWNAME is already
+ in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
+ make a name that is not in use. Interactively, you can make
+ UNIQUE non-`nil' with a numeric prefix argument.
+
+ One application of this command is to rename the `*shell*' buffer
+ to some other name, thus making it possible to create a second
+ shell buffer under the name `*shell*'.
+
+ - Function: get-buffer buffer-or-name
+ This function returns the buffer specified by BUFFER-OR-NAME. If
+ BUFFER-OR-NAME is a string and there is no buffer with that name,
+ the value is `nil'. If BUFFER-OR-NAME is a buffer, it is returned
+ as given. (That is not very useful, so the argument is usually a
+ name.) For example:
+
+ (setq b (get-buffer "lewis"))
+ => #<buffer lewis>
+ (get-buffer b)
+ => #<buffer lewis>
+ (get-buffer "Frazzle-nots")
+ => nil
+
+ See also the function `get-buffer-create' in *Note Creating
+ Buffers::.
+
+ - Function: generate-new-buffer-name starting-name &optional ignore
+ This function returns a name that would be unique for a new
+ buffer--but does not create the buffer. It starts with
+ STARTING-NAME, and produces a name not currently in use for any
+ buffer by appending a number inside of `<...>'.
+
+ If IGNORE is given, it specifies a name that is okay to use (if it
+ is in the sequence to be tried), even if a buffer with that name
+ exists.
+
+ See the related function `generate-new-buffer' in *Note Creating
+ Buffers::.
+
+\1f
+File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
+
+Buffer File Name
+================
+
+ The "buffer file name" is the name of the file that is visited in
+that buffer. When a buffer is not visiting a file, its buffer file name
+is `nil'. Most of the time, the buffer name is the same as the
+nondirectory part of the buffer file name, but the buffer file name and
+the buffer name are distinct and can be set independently. *Note
+Visiting Files::.
+
+ - Function: buffer-file-name &optional buffer
+ This function returns the absolute file name of the file that
+ BUFFER is visiting. If BUFFER is not visiting any file,
+ `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
+ defaults to the current buffer.
+
+ (buffer-file-name (other-buffer))
+ => "/usr/user/lewis/manual/files.texi"
+
+ - Variable: buffer-file-name
+ This buffer-local variable contains the name of the file being
+ visited in the current buffer, or `nil' if it is not visiting a
+ file. It is a permanent local, unaffected by
+ `kill-local-variables'.
+
+ buffer-file-name
+ => "/usr/user/lewis/manual/buffers.texi"
+
+ It is risky to change this variable's value without doing various
+ other things. See the definition of `set-visited-file-name' in
+ `files.el'; some of the things done there, such as changing the
+ buffer name, are not strictly necessary, but others are essential
+ to avoid confusing XEmacs.
+
+ - Variable: buffer-file-truename
+ This buffer-local variable holds the truename of the file visited
+ in the current buffer, or `nil' if no file is visited. It is a
+ permanent local, unaffected by `kill-local-variables'. *Note
+ Truenames::.
+
+ - Variable: buffer-file-number
+ This buffer-local variable holds the file number and directory
+ device number of the file visited in the current buffer, or `nil'
+ if no file or a nonexistent file is visited. It is a permanent
+ local, unaffected by `kill-local-variables'. *Note Truenames::.
+
+ The value is normally a list of the form `(FILENUM DEVNUM)'. This
+ pair of numbers uniquely identifies the file among all files
+ accessible on the system. See the function `file-attributes', in
+ *Note File Attributes::, for more information about them.
+
+ - Function: get-file-buffer filename
+ This function returns the buffer visiting file FILENAME. If there
+ is no such buffer, it returns `nil'. The argument FILENAME, which
+ must be a string, is expanded (*note File Name Expansion::), then
+ compared against the visited file names of all live buffers.
+
+ (get-file-buffer "buffers.texi")
+ => #<buffer buffers.texi>
+
+ In unusual circumstances, there can be more than one buffer
+ visiting the same file name. In such cases, this function returns
+ the first such buffer in the buffer list.
+
+ - Command: set-visited-file-name filename
+ If FILENAME is a non-empty string, this function changes the name
+ of the file visited in current buffer to FILENAME. (If the buffer
+ had no visited file, this gives it one.) The _next time_ the
+ buffer is saved it will go in the newly-specified file. This
+ command marks the buffer as modified, since it does not (as far as
+ XEmacs knows) match the contents of FILENAME, even if it matched
+ the former visited file.
+
+ If FILENAME is `nil' or the empty string, that stands for "no
+ visited file". In this case, `set-visited-file-name' marks the
+ buffer as having no visited file.
+
+ When the function `set-visited-file-name' is called interactively,
+ it prompts for FILENAME in the minibuffer.
+
+ See also `clear-visited-file-modtime' and
+ `verify-visited-file-modtime' in *Note Buffer Modification::.
+
+ - Variable: list-buffers-directory
+ This buffer-local variable records a string to display in a buffer
+ listing in place of the visited file name, for buffers that don't
+ have a visited file name. Dired buffers use this variable.
+
+\1f
+File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
+
+Buffer Modification
+===================
+
+ XEmacs keeps a flag called the "modified flag" for each buffer, to
+record whether you have changed the text of the buffer. This flag is
+set to `t' whenever you alter the contents of the buffer, and cleared
+to `nil' when you save it. Thus, the flag shows whether there are
+unsaved changes. The flag value is normally shown in the modeline
+(*note Modeline Variables::), and controls saving (*note Saving
+Buffers::) and auto-saving (*note Auto-Saving::).
+
+ Some Lisp programs set the flag explicitly. For example, the
+function `set-visited-file-name' sets the flag to `t', because the text
+does not match the newly-visited file, even if it is unchanged from the
+file formerly visited.
+
+ The functions that modify the contents of buffers are described in
+*Note Text::.
+
+ - Function: buffer-modified-p &optional buffer
+ This function returns `t' if the buffer BUFFER has been modified
+ since it was last read in from a file or saved, or `nil'
+ otherwise. If BUFFER is not supplied, the current buffer is
+ tested.
+
+ - Function: set-buffer-modified-p flag
+ This function marks the current buffer as modified if FLAG is
+ non-`nil', or as unmodified if the flag is `nil'.
+
+ Another effect of calling this function is to cause unconditional
+ redisplay of the modeline for the current buffer. In fact, the
+ function `redraw-modeline' works by doing this:
+
+ (set-buffer-modified-p (buffer-modified-p))
+
+ - Command: not-modified &optional arg
+ This command marks the current buffer as unmodified, and not
+ needing to be saved. (If ARG is non-`nil', the buffer is instead
+ marked as modified.) Don't use this function in programs, since it
+ prints a message in the echo area; use `set-buffer-modified-p'
+ (above) instead.
+
+ - Function: buffer-modified-tick &optional buffer
+ This function returns BUFFER`s modification-count. This is a
+ counter that increments every time the buffer is modified. If
+ BUFFER is `nil' (or omitted), the current buffer is used.
+
+\1f
+File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
+
+Comparison of Modification Time
+===============================
+
+ Suppose that you visit a file and make changes in its buffer, and
+meanwhile the file itself is changed on disk. At this point, saving the
+buffer would overwrite the changes in the file. Occasionally this may
+be what you want, but usually it would lose valuable information.
+XEmacs therefore checks the file's modification time using the functions
+described below before saving the file.
+
+ - Function: verify-visited-file-modtime buffer
+ This function compares what BUFFER has recorded for the
+ modification time of its visited file against the actual
+ modification time of the file as recorded by the operating system.
+ The two should be the same unless some other process has written
+ the file since XEmacs visited or saved it.
+
+ The function returns `t' if the last actual modification time and
+ XEmacs's recorded modification time are the same, `nil' otherwise.
+
+ - Function: clear-visited-file-modtime
+ This function clears out the record of the last modification time
+ of the file being visited by the current buffer. As a result, the
+ next attempt to save this buffer will not complain of a
+ discrepancy in file modification times.
+
+ This function is called in `set-visited-file-name' and other
+ exceptional places where the usual test to avoid overwriting a
+ changed file should not be done.
+
+ - Function: visited-file-modtime
+ This function returns the buffer's recorded last file modification
+ time, as a list of the form `(HIGH . LOW)'. (This is the same
+ format that `file-attributes' uses to return time values; see
+ *Note File Attributes::.)
+
+ - Function: set-visited-file-modtime &optional time
+ This function updates the buffer's record of the last modification
+ time of the visited file, to the value specified by TIME if TIME
+ is not `nil', and otherwise to the last modification time of the
+ visited file.
+
+ If TIME is not `nil', it should have the form `(HIGH . LOW)' or
+ `(HIGH LOW)', in either case containing two integers, each of
+ which holds 16 bits of the time.
+
+ This function is useful if the buffer was not read from the file
+ normally, or if the file itself has been changed for some known
+ benign reason.
+
+ - Function: ask-user-about-supersession-threat filename
+ This function is used to ask a user how to proceed after an
+ attempt to modify an obsolete buffer visiting file FILENAME. An
+ "obsolete buffer" is an unmodified buffer for which the associated
+ file on disk is newer than the last save-time of the buffer. This
+ means some other program has probably altered the file.
+
+ Depending on the user's answer, the function may return normally,
+ in which case the modification of the buffer proceeds, or it may
+ signal a `file-supersession' error with data `(FILENAME)', in which
+ case the proposed buffer modification is not allowed.
+
+ This function is called automatically by XEmacs on the proper
+ occasions. It exists so you can customize XEmacs by redefining it.
+ See the file `userlock.el' for the standard definition.
+
+ See also the file locking mechanism in *Note File Locks::.
+
+\1f
+File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
+
+Read-Only Buffers
+=================
+
+ If a buffer is "read-only", then you cannot change its contents,
+although you may change your view of the contents by scrolling and
+narrowing.
+
+ Read-only buffers are used in two kinds of situations:
+
+ * A buffer visiting a write-protected file is normally read-only.
+
+ Here, the purpose is to show the user that editing the buffer with
+ the aim of saving it in the file may be futile or undesirable.
+ The user who wants to change the buffer text despite this can do
+ so after clearing the read-only flag with `C-x C-q'.
+
+ * Modes such as Dired and Rmail make buffers read-only when altering
+ the contents with the usual editing commands is probably a mistake.
+
+ The special commands of these modes bind `buffer-read-only' to
+ `nil' (with `let') or bind `inhibit-read-only' to `t' around the
+ places where they change the text.
+
+ - Variable: buffer-read-only
+ This buffer-local variable specifies whether the buffer is
+ read-only. The buffer is read-only if this variable is non-`nil'.
+
+ - Variable: inhibit-read-only
+ If this variable is non-`nil', then read-only buffers and read-only
+ characters may be modified. Read-only characters in a buffer are
+ those that have non-`nil' `read-only' properties (either text
+ properties or extent properties). *Note Extent Properties::, for
+ more information about text properties and extent properties.
+
+ If `inhibit-read-only' is `t', all `read-only' character
+ properties have no effect. If `inhibit-read-only' is a list, then
+ `read-only' character properties have no effect if they are members
+ of the list (comparison is done with `eq').
+
+ - Command: toggle-read-only
+ This command changes whether the current buffer is read-only. It
+ is intended for interactive use; don't use it in programs. At any
+ given point in a program, you should know whether you want the
+ read-only flag on or off; so you can set `buffer-read-only'
+ explicitly to the proper value, `t' or `nil'.
+
+ - Function: barf-if-buffer-read-only
+ This function signals a `buffer-read-only' error if the current
+ buffer is read-only. *Note Interactive Call::, for another way to
+ signal an error if the current buffer is read-only.
+
+\1f
File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
The Buffer List
This function always returns `nil'.
-\1f
-File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
-
-Selecting Windows
-=================
-
- When a window is selected, the buffer in the window becomes the
-current buffer, and the cursor will appear in it.
-
- - Function: selected-window &optional device
- This function returns the selected window. This is the window in
- which the cursor appears and to which many commands apply. Each
- separate device can have its own selected window, which is
- remembered as focus changes from device to device. Optional
- argument DEVICE specifies which device to return the selected
- window for, and defaults to the selected device.
-
- - Function: select-window window &optional norecord
- This function makes WINDOW the selected window. The cursor then
- appears in WINDOW (on redisplay). The buffer being displayed in
- WINDOW is immediately designated the current buffer.
-
- If optional argument NORECORD is non-`nil' then the global and
- per-frame buffer orderings are not modified, as by the function
- `record-buffer'.
-
- The return value is WINDOW.
-
- (setq w (next-window))
- (select-window w)
- => #<window 65 on windows.texi>
-
- - Macro: save-selected-window forms...
- This macro records the selected window, executes FORMS in
- sequence, then restores the earlier selected window. It does not
- save or restore anything about the sizes, arrangement or contents
- of windows; therefore, if the FORMS change them, the changes are
- permanent.
-
- The following functions choose one of the windows on the screen,
-offering various criteria for the choice.
-
- - Function: get-lru-window &optional frame
- This function returns the window least recently "used" (that is,
- selected). The selected window is always the most recently used
- window.
-
- The selected window can be the least recently used window if it is
- the only window. A newly created window becomes the least
- recently used window until it is selected. A minibuffer window is
- never a candidate.
-
- The argument FRAME controls which windows are considered.
-
- * If it is `nil', consider windows on the selected frame.
-
- * If it is `t', consider windows on all frames.
-
- * If it is `visible', consider windows on all visible frames.
-
- * If it is 0, consider windows on all visible or iconified
- frames.
-
- * If it is a frame, consider windows on that frame.
-
- - Function: get-largest-window &optional frame
- This function returns the window with the largest area (height
- times width). If there are no side-by-side windows, then this is
- the window with the most lines. A minibuffer window is never a
- candidate.
-
- If there are two windows of the same size, then the function
- returns the window that is first in the cyclic ordering of windows
- (see following section), starting from the selected window.
-
- The argument FRAME controls which set of windows are considered.
- See `get-lru-window', above.
-
-\1f
-File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
-
-Cyclic Ordering of Windows
-==========================
-
- When you use the command `C-x o' (`other-window') to select the next
-window, it moves through all the windows on the screen in a specific
-cyclic order. For any given configuration of windows, this order never
-varies. It is called the "cyclic ordering of windows".
-
- This ordering generally goes from top to bottom, and from left to
-right. But it may go down first or go right first, depending on the
-order in which the windows were split.
-
- If the first split was vertical (into windows one above each other),
-and then the subwindows were split horizontally, then the ordering is
-left to right in the top of the frame, and then left to right in the
-next lower part of the frame, and so on. If the first split was
-horizontal, the ordering is top to bottom in the left part, and so on.
-In general, within each set of siblings at any level in the window tree,
-the order is left to right, or top to bottom.
-
- - Function: next-window &optional window minibuf all-frames
- This function returns the window following WINDOW in the cyclic
- ordering of windows. This is the window that `C-x o' would select
- if typed when WINDOW is selected. If WINDOW is the only window
- visible, then this function returns WINDOW. If omitted, WINDOW
- defaults to the selected window.
-
- The value of the argument MINIBUF determines whether the
- minibuffer is included in the window order. Normally, when
- MINIBUF is `nil', the minibuffer is included if it is currently
- active; this is the behavior of `C-x o'. (The minibuffer window
- is active while the minibuffer is in use. *Note Minibuffers::.)
-
- If MINIBUF is `t', then the cyclic ordering includes the
- minibuffer window even if it is not active.
-
- If MINIBUF is neither `t' nor `nil', then the minibuffer window is
- not included even if it is active.
-
- The argument ALL-FRAMES specifies which frames to consider. Here
- are the possible values and their meanings:
-
- `nil'
- Consider all the windows in WINDOW's frame, plus the
- minibuffer used by that frame even if it lies in some other
- frame.
-
- `t'
- Consider all windows in all existing frames.
-
- `visible'
- Consider all windows in all visible frames. (To get useful
- results, you must ensure WINDOW is in a visible frame.)
-
- 0
- Consider all windows in all visible or iconified frames.
-
- anything else
- Consider precisely the windows in WINDOW's frame, and no
- others.
-
- This example assumes there are two windows, both displaying the
- buffer `windows.texi':
-
- (selected-window)
- => #<window 56 on windows.texi>
- (next-window (selected-window))
- => #<window 52 on windows.texi>
- (next-window (next-window (selected-window)))
- => #<window 56 on windows.texi>
-
- - Function: previous-window &optional window minibuf all-frames
- This function returns the window preceding WINDOW in the cyclic
- ordering of windows. The other arguments specify which windows to
- include in the cycle, as in `next-window'.
-
- - Command: other-window count &optional frame
- This function selects the COUNTth following window in the cyclic
- order. If count is negative, then it selects the -COUNTth
- preceding window. It returns `nil'.
-
- In an interactive call, COUNT is the numeric prefix argument.
-
- The argument FRAME controls which set of windows are considered.
- * If it is `nil' or omitted, then windows on the selected frame
- are considered.
-
- * If it is a frame, then windows on that frame are considered.
-
- * If it is `t', then windows on all frames that currently exist
- (including invisible and iconified frames) are considered.
-
- * If it is the symbol `visible', then windows on all visible
- frames are considered.
-
- * If it is the number 0, then windows on all visible and
- iconified frames are considered.
-
- * If it is any other value, then the behavior is undefined.
-
- - Function: walk-windows proc &optional minibuf all-frames
- This function cycles through all windows, calling `proc' once for
- each window with the window as its sole argument.
-
- The optional arguments MINIBUF and ALL-FRAMES specify the set of
- windows to include in the scan. See `next-window', above, for
- details.
-
-\1f
-File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
-
-Buffers and Windows
-===================
-
- This section describes low-level functions to examine windows or to
-display buffers in windows in a precisely controlled fashion. *Note
-Displaying Buffers::, for related functions that find a window to use
-and specify a buffer for it. The functions described there are easier
-to use than these, but they employ heuristics in choosing or creating a
-window; use these functions when you need complete control.
-
- - Function: set-window-buffer window buffer-or-name
- This function makes WINDOW display BUFFER-OR-NAME as its contents.
- It returns `nil'.
-
- (set-window-buffer (selected-window) "foo")
- => nil
-
- - Function: window-buffer &optional window
- This function returns the buffer that WINDOW is displaying. If
- WINDOW is omitted, this function returns the buffer for the
- selected window.
-
- (window-buffer)
- => #<buffer windows.texi>
-
- - Function: get-buffer-window buffer-or-name &optional frame
- This function returns a window currently displaying
- BUFFER-OR-NAME, or `nil' if there is none. If there are several
- such windows, then the function returns the first one in the
- cyclic ordering of windows, starting from the selected window.
- *Note Cyclic Window Ordering::.
-
- The argument ALL-FRAMES controls which windows to consider.
-
- * If it is `nil', consider windows on the selected frame.
-
- * If it is `t', consider windows on all frames.
-
- * If it is `visible', consider windows on all visible frames.
-
- * If it is 0, consider windows on all visible or iconified
- frames.
-
- * If it is a frame, consider windows on that frame.
-
-\1f
-File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
-
-Displaying Buffers in Windows
-=============================
-
- In this section we describe convenient functions that choose a window
-automatically and use it to display a specified buffer. These functions
-can also split an existing window in certain circumstances. We also
-describe variables that parameterize the heuristics used for choosing a
-window. *Note Buffers and Windows::, for low-level functions that give
-you more precise control.
-
- Do not use the functions in this section in order to make a buffer
-current so that a Lisp program can access or modify it; they are too
-drastic for that purpose, since they change the display of buffers in
-windows, which is gratuitous and will surprise the user. Instead, use
-`set-buffer' (*note Current Buffer::) and `save-excursion' (*note
-Excursions::), which designate buffers as current for programmed access
-without affecting the display of buffers in windows.
-
- - Command: switch-to-buffer buffer-or-name &optional norecord
- This function makes BUFFER-OR-NAME the current buffer, and also
- displays the buffer in the selected window. This means that a
- human can see the buffer and subsequent keyboard commands will
- apply to it. Contrast this with `set-buffer', which makes
- BUFFER-OR-NAME the current buffer but does not display it in the
- selected window. *Note Current Buffer::.
-
- If BUFFER-OR-NAME does not identify an existing buffer, then a new
- buffer by that name is created. The major mode for the new buffer
- is set according to the variable `default-major-mode'. *Note Auto
- Major Mode::.
-
- Normally the specified buffer is put at the front of the buffer
- list. This affects the operation of `other-buffer'. However, if
- NORECORD is non-`nil', this is not done. *Note The Buffer List::.
-
- The `switch-to-buffer' function is often used interactively, as
- the binding of `C-x b'. It is also used frequently in programs.
- It always returns `nil'.
-
- - Command: switch-to-buffer-other-window buffer-or-name
- This function makes BUFFER-OR-NAME the current buffer and displays
- it in a window not currently selected. It then selects that
- window. The handling of the buffer is the same as in
- `switch-to-buffer'.
-
- The currently selected window is absolutely never used to do the
- job. If it is the only window, then it is split to make a
- distinct window for this purpose. If the selected window is
- already displaying the buffer, then it continues to do so, but
- another window is nonetheless found to display it in as well.
-
- - Function: pop-to-buffer buffer-or-name &optional other-window
- on-frame
- This function makes BUFFER-OR-NAME the current buffer and switches
- to it in some window, preferably not the window previously
- selected. The "popped-to" window becomes the selected window
- within its frame.
-
- If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
- looks for a window in any visible frame already displaying the
- buffer; if there is one, it returns that window and makes it be
- selected within its frame. If there is none, it creates a new
- frame and displays the buffer in it.
-
- If `pop-up-frames' is `nil', then `pop-to-buffer' operates
- entirely within the selected frame. (If the selected frame has
- just a minibuffer, `pop-to-buffer' operates within the most
- recently selected frame that was not just a minibuffer.)
-
- If the variable `pop-up-windows' is non-`nil', windows may be
- split to create a new window that is different from the original
- window. For details, see *Note Choosing Window::.
-
- If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
- another window even if BUFFER-OR-NAME is already visible in the
- selected window. Thus BUFFER-OR-NAME could end up displayed in
- two windows. On the other hand, if BUFFER-OR-NAME is already
- displayed in the selected window and OTHER-WINDOW is `nil', then
- the selected window is considered sufficient display for
- BUFFER-OR-NAME, so that nothing needs to be done.
-
- All the variables that affect `display-buffer' affect
- `pop-to-buffer' as well. *Note Choosing Window::.
-
- If BUFFER-OR-NAME is a string that does not name an existing
- buffer, a buffer by that name is created. The major mode for the
- new buffer is set according to the variable `default-major-mode'.
- *Note Auto Major Mode::.
-
- If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
-
- An example use of this function is found at the end of *Note
- Filter Functions::.
-
- - Command: replace-buffer-in-windows buffer
- This function replaces BUFFER with some other buffer in all
- windows displaying it. The other buffer used is chosen with
- `other-buffer'. In the usual applications of this function, you
- don't care which other buffer is used; you just want to make sure
- that BUFFER is no longer displayed.
-
- This function returns `nil'.
-
-\1f
-File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
-
-Choosing a Window for Display
-=============================
-
- This section describes the basic facility that chooses a window to
-display a buffer in--`display-buffer'. All the higher-level functions
-and commands use this subroutine. Here we describe how to use
-`display-buffer' and how to customize it.
-
- - Command: display-buffer buffer-or-name &optional not-this-window
- This command makes BUFFER-OR-NAME appear in some window, like
- `pop-to-buffer', but it does not select that window and does not
- make the buffer current. The identity of the selected window is
- unaltered by this function.
-
- If NOT-THIS-WINDOW is non-`nil', it means to display the specified
- buffer in a window other than the selected one, even if it is
- already on display in the selected window. This can cause the
- buffer to appear in two windows at once. Otherwise, if
- BUFFER-OR-NAME is already being displayed in any window, that is
- good enough, so this function does nothing.
-
- `display-buffer' returns the window chosen to display
- BUFFER-OR-NAME.
-
- Precisely how `display-buffer' finds or creates a window depends on
- the variables described below.
-
- A window can be marked as "dedicated" to a particular buffer. Then
-XEmacs will not automatically change which buffer appears in the
-window, such as `display-buffer' might normally do.
-
- - Function: window-dedicated-p window
- This function returns WINDOW's dedicated object, usually `t' or
- `nil'.
-
- - Function: set-window-buffer-dedicated window buffer
- This function makes WINDOW display BUFFER and be dedicated to that
- buffer. Then XEmacs will not automatically change which buffer
- appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
- not be dedicated (but doesn't change which buffer appears in it
- currently).
-
- - User Option: pop-up-windows
- This variable controls whether `display-buffer' makes new windows.
- If it is non-`nil' and there is only one window, then that window
- is split. If it is `nil', then `display-buffer' does not split
- the single window, but uses it whole.
-
- - User Option: split-height-threshold
- This variable determines when `display-buffer' may split a window,
- if there are multiple windows. `display-buffer' always splits the
- largest window if it has at least this many lines. If the largest
- window is not this tall, it is split only if it is the sole window
- and `pop-up-windows' is non-`nil'.
-
- - User Option: pop-up-frames
- This variable controls whether `display-buffer' makes new frames.
- If it is non-`nil', `display-buffer' looks for an existing window
- already displaying the desired buffer, on any visible frame. If
- it finds one, it returns that window. Otherwise it makes a new
- frame. The variables `pop-up-windows' and
- `split-height-threshold' do not matter if `pop-up-frames' is
- non-`nil'.
-
- If `pop-up-frames' is `nil', then `display-buffer' either splits a
- window or reuses one.
-
- *Note Frames::, for more information.
-
- - Variable: pop-up-frame-function
- This variable specifies how to make a new frame if `pop-up-frames'
- is non-`nil'.
-
- Its value should be a function of no arguments. When
- `display-buffer' makes a new frame, it does so by calling that
- function, which should return a frame. The default value of the
- variable is a function that creates a frame using properties from
- `pop-up-frame-plist'.
-
- - Variable: pop-up-frame-plist
- This variable holds a plist specifying frame properties used when
- `display-buffer' makes a new frame. *Note Frame Properties::, for
- more information about frame properties.
-
- - Variable: special-display-buffer-names
- A list of buffer names for buffers that should be displayed
- specially. If the buffer's name is in this list, `display-buffer'
- handles the buffer specially.
-
- By default, special display means to give the buffer a dedicated
- frame.
-
- If an element is a list, instead of a string, then the CAR of the
- list is the buffer name, and the rest of the list says how to
- create the frame. There are two possibilities for the rest of the
- list. It can be a plist, specifying frame properties, or it can
- contain a function and arguments to give to it. (The function's
- first argument is always the buffer to be displayed; the arguments
- from the list come after that.)
-
- - Variable: special-display-regexps
- A list of regular expressions that specify buffers that should be
- displayed specially. If the buffer's name matches any of the
- regular expressions in this list, `display-buffer' handles the
- buffer specially.
-
- By default, special display means to give the buffer a dedicated
- frame.
-
- If an element is a list, instead of a string, then the CAR of the
- list is the regular expression, and the rest of the list says how
- to create the frame. See above, under
- `special-display-buffer-names'.
-
- - Variable: special-display-function
- This variable holds the function to call to display a buffer
- specially. It receives the buffer as an argument, and should
- return the window in which it is displayed.
-
- The default value of this variable is
- `special-display-popup-frame'.
-
- - Function: special-display-popup-frame buffer
- This function makes BUFFER visible in a frame of its own. If
- BUFFER is already displayed in a window in some frame, it makes
- the frame visible and raises it, to use that window. Otherwise, it
- creates a frame that will be dedicated to BUFFER.
-
- This function uses an existing window displaying BUFFER whether or
- not it is in a frame of its own; but if you set up the above
- variables in your init file, before BUFFER was created, then
- presumably the window was previously made by this function.
-
- - User Option: special-display-frame-plist
- This variable holds frame properties for
- `special-display-popup-frame' to use when it creates a frame.
-
- - Variable: same-window-buffer-names
- A list of buffer names for buffers that should be displayed in the
- selected window. If the buffer's name is in this list,
- `display-buffer' handles the buffer by switching to it in the
- selected window.
-
- - Variable: same-window-regexps
- A list of regular expressions that specify buffers that should be
- displayed in the selected window. If the buffer's name matches
- any of the regular expressions in this list, `display-buffer'
- handles the buffer by switching to it in the selected window.
-
- - Variable: display-buffer-function
- This variable is the most flexible way to customize the behavior of
- `display-buffer'. If it is non-`nil', it should be a function
- that `display-buffer' calls to do the work. The function should
- accept two arguments, the same two arguments that `display-buffer'
- received. It should choose or create a window, display the
- specified buffer, and then return the window.
-
- This hook takes precedence over all the other options and hooks
- described above.
-
- A window can be marked as "dedicated" to its buffer. Then
-`display-buffer' does not try to use that window.
-
- - Function: window-dedicated-p window
- This function returns `t' if WINDOW is marked as dedicated;
- otherwise `nil'.
-
- - Function: set-window-dedicated-p window flag
- This function marks WINDOW as dedicated if FLAG is non-`nil', and
- nondedicated otherwise.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
+
+Selecting Windows
+=================
+
+ When a window is selected, the buffer in the window becomes the
+current buffer, and the cursor will appear in it.
+
+ - Function: selected-window &optional device
+ This function returns the selected window. This is the window in
+ which the cursor appears and to which many commands apply. Each
+ separate device can have its own selected window, which is
+ remembered as focus changes from device to device. Optional
+ argument DEVICE specifies which device to return the selected
+ window for, and defaults to the selected device.
+
+ - Function: select-window window &optional norecord
+ This function makes WINDOW the selected window. The cursor then
+ appears in WINDOW (on redisplay). The buffer being displayed in
+ WINDOW is immediately designated the current buffer.
+
+ If optional argument NORECORD is non-`nil' then the global and
+ per-frame buffer orderings are not modified, as by the function
+ `record-buffer'.
+
+ The return value is WINDOW.
+
+ (setq w (next-window))
+ (select-window w)
+ => #<window 65 on windows.texi>
+
+ - Macro: save-selected-window forms...
+ This macro records the selected window, executes FORMS in
+ sequence, then restores the earlier selected window. It does not
+ save or restore anything about the sizes, arrangement or contents
+ of windows; therefore, if the FORMS change them, the changes are
+ permanent.
+
+ The following functions choose one of the windows on the screen,
+offering various criteria for the choice.
+
+ - Function: get-lru-window &optional frame
+ This function returns the window least recently "used" (that is,
+ selected). The selected window is always the most recently used
+ window.
+
+ The selected window can be the least recently used window if it is
+ the only window. A newly created window becomes the least
+ recently used window until it is selected. A minibuffer window is
+ never a candidate.
+
+ The argument FRAME controls which windows are considered.
+
+ * If it is `nil', consider windows on the selected frame.
+
+ * If it is `t', consider windows on all frames.
+
+ * If it is `visible', consider windows on all visible frames.
+
+ * If it is 0, consider windows on all visible or iconified
+ frames.
+
+ * If it is a frame, consider windows on that frame.
+
+ - Function: get-largest-window &optional frame
+ This function returns the window with the largest area (height
+ times width). If there are no side-by-side windows, then this is
+ the window with the most lines. A minibuffer window is never a
+ candidate.
+
+ If there are two windows of the same size, then the function
+ returns the window that is first in the cyclic ordering of windows
+ (see following section), starting from the selected window.
+
+ The argument FRAME controls which set of windows are considered.
+ See `get-lru-window', above.
+
+\1f
+File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
+
+Cyclic Ordering of Windows
+==========================
+
+ When you use the command `C-x o' (`other-window') to select the next
+window, it moves through all the windows on the screen in a specific
+cyclic order. For any given configuration of windows, this order never
+varies. It is called the "cyclic ordering of windows".
+
+ This ordering generally goes from top to bottom, and from left to
+right. But it may go down first or go right first, depending on the
+order in which the windows were split.
+
+ If the first split was vertical (into windows one above each other),
+and then the subwindows were split horizontally, then the ordering is
+left to right in the top of the frame, and then left to right in the
+next lower part of the frame, and so on. If the first split was
+horizontal, the ordering is top to bottom in the left part, and so on.
+In general, within each set of siblings at any level in the window tree,
+the order is left to right, or top to bottom.
+
+ - Function: next-window &optional window minibuf all-frames
+ This function returns the window following WINDOW in the cyclic
+ ordering of windows. This is the window that `C-x o' would select
+ if typed when WINDOW is selected. If WINDOW is the only window
+ visible, then this function returns WINDOW. If omitted, WINDOW
+ defaults to the selected window.
+
+ The value of the argument MINIBUF determines whether the
+ minibuffer is included in the window order. Normally, when
+ MINIBUF is `nil', the minibuffer is included if it is currently
+ active; this is the behavior of `C-x o'. (The minibuffer window
+ is active while the minibuffer is in use. *Note Minibuffers::.)
+
+ If MINIBUF is `t', then the cyclic ordering includes the
+ minibuffer window even if it is not active.
+
+ If MINIBUF is neither `t' nor `nil', then the minibuffer window is
+ not included even if it is active.
+
+ The argument ALL-FRAMES specifies which frames to consider. Here
+ are the possible values and their meanings:
+
+ `nil'
+ Consider all the windows in WINDOW's frame, plus the
+ minibuffer used by that frame even if it lies in some other
+ frame.
+
+ `t'
+ Consider all windows in all existing frames.
+
+ `visible'
+ Consider all windows in all visible frames. (To get useful
+ results, you must ensure WINDOW is in a visible frame.)
+
+ 0
+ Consider all windows in all visible or iconified frames.
+
+ anything else
+ Consider precisely the windows in WINDOW's frame, and no
+ others.
+
+ This example assumes there are two windows, both displaying the
+ buffer `windows.texi':
+
+ (selected-window)
+ => #<window 56 on windows.texi>
+ (next-window (selected-window))
+ => #<window 52 on windows.texi>
+ (next-window (next-window (selected-window)))
+ => #<window 56 on windows.texi>
+
+ - Function: previous-window &optional window minibuf all-frames
+ This function returns the window preceding WINDOW in the cyclic
+ ordering of windows. The other arguments specify which windows to
+ include in the cycle, as in `next-window'.
+
+ - Command: other-window count &optional frame
+ This function selects the COUNTth following window in the cyclic
+ order. If count is negative, then it selects the -COUNTth
+ preceding window. It returns `nil'.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ The argument FRAME controls which set of windows are considered.
+ * If it is `nil' or omitted, then windows on the selected frame
+ are considered.
+
+ * If it is a frame, then windows on that frame are considered.
+
+ * If it is `t', then windows on all frames that currently exist
+ (including invisible and iconified frames) are considered.
+
+ * If it is the symbol `visible', then windows on all visible
+ frames are considered.
+
+ * If it is the number 0, then windows on all visible and
+ iconified frames are considered.
+
+ * If it is any other value, then the behavior is undefined.
+
+ - Function: walk-windows proc &optional minibuf all-frames
+ This function cycles through all windows, calling `proc' once for
+ each window with the window as its sole argument.
+
+ The optional arguments MINIBUF and ALL-FRAMES specify the set of
+ windows to include in the scan. See `next-window', above, for
+ details.
+
+\1f
+File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
+
+Buffers and Windows
+===================
+
+ This section describes low-level functions to examine windows or to
+display buffers in windows in a precisely controlled fashion. *Note
+Displaying Buffers::, for related functions that find a window to use
+and specify a buffer for it. The functions described there are easier
+to use than these, but they employ heuristics in choosing or creating a
+window; use these functions when you need complete control.
+
+ - Function: set-window-buffer window buffer-or-name
+ This function makes WINDOW display BUFFER-OR-NAME as its contents.
+ It returns `nil'.
+
+ (set-window-buffer (selected-window) "foo")
+ => nil
+
+ - Function: window-buffer &optional window
+ This function returns the buffer that WINDOW is displaying. If
+ WINDOW is omitted, this function returns the buffer for the
+ selected window.
+
+ (window-buffer)
+ => #<buffer windows.texi>
+
+ - Function: get-buffer-window buffer-or-name &optional frame
+ This function returns a window currently displaying
+ BUFFER-OR-NAME, or `nil' if there is none. If there are several
+ such windows, then the function returns the first one in the
+ cyclic ordering of windows, starting from the selected window.
+ *Note Cyclic Window Ordering::.
+
+ The argument ALL-FRAMES controls which windows to consider.
+
+ * If it is `nil', consider windows on the selected frame.
+
+ * If it is `t', consider windows on all frames.
+
+ * If it is `visible', consider windows on all visible frames.
+
+ * If it is 0, consider windows on all visible or iconified
+ frames.
+
+ * If it is a frame, consider windows on that frame.
+
+\1f
+File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
+
+Displaying Buffers in Windows
+=============================
+
+ In this section we describe convenient functions that choose a window
+automatically and use it to display a specified buffer. These functions
+can also split an existing window in certain circumstances. We also
+describe variables that parameterize the heuristics used for choosing a
+window. *Note Buffers and Windows::, for low-level functions that give
+you more precise control.
+
+ Do not use the functions in this section in order to make a buffer
+current so that a Lisp program can access or modify it; they are too
+drastic for that purpose, since they change the display of buffers in
+windows, which is gratuitous and will surprise the user. Instead, use
+`set-buffer' (*note Current Buffer::) and `save-excursion' (*note
+Excursions::), which designate buffers as current for programmed access
+without affecting the display of buffers in windows.
+
+ - Command: switch-to-buffer buffer-or-name &optional norecord
+ This function makes BUFFER-OR-NAME the current buffer, and also
+ displays the buffer in the selected window. This means that a
+ human can see the buffer and subsequent keyboard commands will
+ apply to it. Contrast this with `set-buffer', which makes
+ BUFFER-OR-NAME the current buffer but does not display it in the
+ selected window. *Note Current Buffer::.
+
+ If BUFFER-OR-NAME does not identify an existing buffer, then a new
+ buffer by that name is created. The major mode for the new buffer
+ is set according to the variable `default-major-mode'. *Note Auto
+ Major Mode::.
+
+ Normally the specified buffer is put at the front of the buffer
+ list. This affects the operation of `other-buffer'. However, if
+ NORECORD is non-`nil', this is not done. *Note The Buffer List::.
+
+ The `switch-to-buffer' function is often used interactively, as
+ the binding of `C-x b'. It is also used frequently in programs.
+ It always returns `nil'.
+
+ - Command: switch-to-buffer-other-window buffer-or-name
+ This function makes BUFFER-OR-NAME the current buffer and displays
+ it in a window not currently selected. It then selects that
+ window. The handling of the buffer is the same as in
+ `switch-to-buffer'.
+
+ The currently selected window is absolutely never used to do the
+ job. If it is the only window, then it is split to make a
+ distinct window for this purpose. If the selected window is
+ already displaying the buffer, then it continues to do so, but
+ another window is nonetheless found to display it in as well.
+
+ - Function: pop-to-buffer buffer-or-name &optional other-window
+ on-frame
+ This function makes BUFFER-OR-NAME the current buffer and switches
+ to it in some window, preferably not the window previously
+ selected. The "popped-to" window becomes the selected window
+ within its frame.
+
+ If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
+ looks for a window in any visible frame already displaying the
+ buffer; if there is one, it returns that window and makes it be
+ selected within its frame. If there is none, it creates a new
+ frame and displays the buffer in it.
+
+ If `pop-up-frames' is `nil', then `pop-to-buffer' operates
+ entirely within the selected frame. (If the selected frame has
+ just a minibuffer, `pop-to-buffer' operates within the most
+ recently selected frame that was not just a minibuffer.)
+
+ If the variable `pop-up-windows' is non-`nil', windows may be
+ split to create a new window that is different from the original
+ window. For details, see *Note Choosing Window::.
+
+ If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
+ another window even if BUFFER-OR-NAME is already visible in the
+ selected window. Thus BUFFER-OR-NAME could end up displayed in
+ two windows. On the other hand, if BUFFER-OR-NAME is already
+ displayed in the selected window and OTHER-WINDOW is `nil', then
+ the selected window is considered sufficient display for
+ BUFFER-OR-NAME, so that nothing needs to be done.
+
+ All the variables that affect `display-buffer' affect
+ `pop-to-buffer' as well. *Note Choosing Window::.
+
+ If BUFFER-OR-NAME is a string that does not name an existing
+ buffer, a buffer by that name is created. The major mode for the
+ new buffer is set according to the variable `default-major-mode'.
+ *Note Auto Major Mode::.
+
+ If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
+
+ An example use of this function is found at the end of *Note
+ Filter Functions::.
+
+ - Command: replace-buffer-in-windows buffer
+ This function replaces BUFFER with some other buffer in all
+ windows displaying it. The other buffer used is chosen with
+ `other-buffer'. In the usual applications of this function, you
+ don't care which other buffer is used; you just want to make sure
+ that BUFFER is no longer displayed.
+
+ This function returns `nil'.
+
+\1f
+File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
+
+Choosing a Window for Display
+=============================
+
+ This section describes the basic facility that chooses a window to
+display a buffer in--`display-buffer'. All the higher-level functions
+and commands use this subroutine. Here we describe how to use
+`display-buffer' and how to customize it.
+
+ - Command: display-buffer buffer-or-name &optional not-this-window
+ This command makes BUFFER-OR-NAME appear in some window, like
+ `pop-to-buffer', but it does not select that window and does not
+ make the buffer current. The identity of the selected window is
+ unaltered by this function.
+
+ If NOT-THIS-WINDOW is non-`nil', it means to display the specified
+ buffer in a window other than the selected one, even if it is
+ already on display in the selected window. This can cause the
+ buffer to appear in two windows at once. Otherwise, if
+ BUFFER-OR-NAME is already being displayed in any window, that is
+ good enough, so this function does nothing.
+
+ `display-buffer' returns the window chosen to display
+ BUFFER-OR-NAME.
+
+ Precisely how `display-buffer' finds or creates a window depends on
+ the variables described below.
+
+ A window can be marked as "dedicated" to a particular buffer. Then
+XEmacs will not automatically change which buffer appears in the
+window, such as `display-buffer' might normally do.
+
+ - Function: window-dedicated-p window
+ This function returns WINDOW's dedicated object, usually `t' or
+ `nil'.
+
+ - Function: set-window-buffer-dedicated window buffer
+ This function makes WINDOW display BUFFER and be dedicated to that
+ buffer. Then XEmacs will not automatically change which buffer
+ appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
+ not be dedicated (but doesn't change which buffer appears in it
+ currently).
+
+ - User Option: pop-up-windows
+ This variable controls whether `display-buffer' makes new windows.
+ If it is non-`nil' and there is only one window, then that window
+ is split. If it is `nil', then `display-buffer' does not split
+ the single window, but uses it whole.
+
+ - User Option: split-height-threshold
+ This variable determines when `display-buffer' may split a window,
+ if there are multiple windows. `display-buffer' always splits the
+ largest window if it has at least this many lines. If the largest
+ window is not this tall, it is split only if it is the sole window
+ and `pop-up-windows' is non-`nil'.
+
+ - User Option: pop-up-frames
+ This variable controls whether `display-buffer' makes new frames.
+ If it is non-`nil', `display-buffer' looks for an existing window
+ already displaying the desired buffer, on any visible frame. If
+ it finds one, it returns that window. Otherwise it makes a new
+ frame. The variables `pop-up-windows' and
+ `split-height-threshold' do not matter if `pop-up-frames' is
+ non-`nil'.
+
+ If `pop-up-frames' is `nil', then `display-buffer' either splits a
+ window or reuses one.
+
+ *Note Frames::, for more information.
+
+ - Variable: pop-up-frame-function
+ This variable specifies how to make a new frame if `pop-up-frames'
+ is non-`nil'.
+
+ Its value should be a function of no arguments. When
+ `display-buffer' makes a new frame, it does so by calling that
+ function, which should return a frame. The default value of the
+ variable is a function that creates a frame using properties from
+ `pop-up-frame-plist'.
+
+ - Variable: pop-up-frame-plist
+ This variable holds a plist specifying frame properties used when
+ `display-buffer' makes a new frame. *Note Frame Properties::, for
+ more information about frame properties.
+
+ - Variable: special-display-buffer-names
+ A list of buffer names for buffers that should be displayed
+ specially. If the buffer's name is in this list, `display-buffer'
+ handles the buffer specially.
+
+ By default, special display means to give the buffer a dedicated
+ frame.
+
+ If an element is a list, instead of a string, then the CAR of the
+ list is the buffer name, and the rest of the list says how to
+ create the frame. There are two possibilities for the rest of the
+ list. It can be a plist, specifying frame properties, or it can
+ contain a function and arguments to give to it. (The function's
+ first argument is always the buffer to be displayed; the arguments
+ from the list come after that.)
+
+ - Variable: special-display-regexps
+ A list of regular expressions that specify buffers that should be
+ displayed specially. If the buffer's name matches any of the
+ regular expressions in this list, `display-buffer' handles the
+ buffer specially.
+
+ By default, special display means to give the buffer a dedicated
+ frame.
+
+ If an element is a list, instead of a string, then the CAR of the
+ list is the regular expression, and the rest of the list says how
+ to create the frame. See above, under
+ `special-display-buffer-names'.
+
+ - Variable: special-display-function
+ This variable holds the function to call to display a buffer
+ specially. It receives the buffer as an argument, and should
+ return the window in which it is displayed.
+
+ The default value of this variable is
+ `special-display-popup-frame'.
+
+ - Function: special-display-popup-frame buffer
+ This function makes BUFFER visible in a frame of its own. If
+ BUFFER is already displayed in a window in some frame, it makes
+ the frame visible and raises it, to use that window. Otherwise, it
+ creates a frame that will be dedicated to BUFFER.
+
+ This function uses an existing window displaying BUFFER whether or
+ not it is in a frame of its own; but if you set up the above
+ variables in your init file, before BUFFER was created, then
+ presumably the window was previously made by this function.
+
+ - User Option: special-display-frame-plist
+ This variable holds frame properties for
+ `special-display-popup-frame' to use when it creates a frame.
+
+ - Variable: same-window-buffer-names
+ A list of buffer names for buffers that should be displayed in the
+ selected window. If the buffer's name is in this list,
+ `display-buffer' handles the buffer by switching to it in the
+ selected window.
+
+ - Variable: same-window-regexps
+ A list of regular expressions that specify buffers that should be
+ displayed in the selected window. If the buffer's name matches
+ any of the regular expressions in this list, `display-buffer'
+ handles the buffer by switching to it in the selected window.
+
+ - Variable: display-buffer-function
+ This variable is the most flexible way to customize the behavior of
+ `display-buffer'. If it is non-`nil', it should be a function
+ that `display-buffer' calls to do the work. The function should
+ accept two arguments, the same two arguments that `display-buffer'
+ received. It should choose or create a window, display the
+ specified buffer, and then return the window.
+
+ This hook takes precedence over all the other options and hooks
+ described above.
+
+ A window can be marked as "dedicated" to its buffer. Then
+`display-buffer' does not try to use that window.
+
+ - Function: window-dedicated-p window
+ This function returns `t' if WINDOW is marked as dedicated;
+ otherwise `nil'.
+
+ - Function: set-window-dedicated-p window flag
+ This function marks WINDOW as dedicated if FLAG is non-`nil', and
+ nondedicated otherwise.
+
+\1f
File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows
Windows and Point
bottom)', all relative to `(0,0)' at the top left corner of the
window.
-\1f
-File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows
-
-Changing the Size of a Window
-=============================
-
- The window size functions fall into two classes: high-level commands
-that change the size of windows and low-level functions that access
-window size. XEmacs does not permit overlapping windows or gaps between
-windows, so resizing one window affects other windows.
-
- - Command: enlarge-window size &optional horizontal window
- This function makes the selected window SIZE lines taller,
- stealing lines from neighboring windows. It takes the lines from
- one window at a time until that window is used up, then takes from
- another. If a window from which lines are stolen shrinks below
- `window-min-height' lines, that window disappears.
-
- If HORIZONTAL is non-`nil', this function makes WINDOW wider by
- SIZE columns, stealing columns instead of lines. If a window from
- which columns are stolen shrinks below `window-min-width' columns,
- that window disappears.
-
- If the requested size would exceed that of the window's frame,
- then the function makes the window occupy the entire height (or
- width) of the frame.
-
- If SIZE is negative, this function shrinks the window by -SIZE
- lines or columns. If that makes the window smaller than the
- minimum size (`window-min-height' and `window-min-width'),
- `enlarge-window' deletes the window.
-
- If WINDOW is non-`nil', it specifies a window to change instead of
- the selected window.
-
- `enlarge-window' returns `nil'.
-
- - Command: enlarge-window-horizontally columns
- This function makes the selected window COLUMNS wider. It could
- be defined as follows:
-
- (defun enlarge-window-horizontally (columns)
- (enlarge-window columns t))
-
- - Command: enlarge-window-pixels count &optional side window
- This function makes the selected window COUNT pixels larger. When
- called from Lisp, optional second argument SIDE non-`nil' means to
- grow sideways COUNT pixels, and optional third argument WINDOW
- specifies the window to change instead of the selected window.
-
- - Command: shrink-window size &optional horizontal window
- This function is like `enlarge-window' but negates the argument
- SIZE, making the selected window smaller by giving lines (or
- columns) to the other windows. If the window shrinks below
- `window-min-height' or `window-min-width', then it disappears.
-
- If SIZE is negative, the window is enlarged by -SIZE lines or
- columns.
-
- If WINDOW is non-`nil', it specifies a window to change instead of
- the selected window.
-
- - Command: shrink-window-horizontally columns
- This function makes the selected window COLUMNS narrower. It
- could be defined as follows:
-
- (defun shrink-window-horizontally (columns)
- (shrink-window columns t))
-
- - Command: shrink-window-pixels count &optional side window
- This function makes the selected window COUNT pixels smaller.
- When called from Lisp, optional second argument SIDE non-`nil'
- means to shrink sideways COUNT pixels, and optional third argument
- WINDOW specifies the window to change instead of the selected
- window.
-
- The following two variables constrain the window-size-changing
-functions to a minimum height and width.
-
- - User Option: window-min-height
- The value of this variable determines how short a window may become
- before it is automatically deleted. Making a window smaller than
- `window-min-height' automatically deletes it, and no window may be
- created shorter than this. The absolute minimum height is two
- (allowing one line for the mode line, and one line for the buffer
- display). Actions that change window sizes reset this variable to
- two if it is less than two. The default value is 4.
-
- - User Option: window-min-width
- The value of this variable determines how narrow a window may
- become before it automatically deleted. Making a window smaller
- than `window-min-width' automatically deletes it, and no window
- may be created narrower than this. The absolute minimum width is
- one; any value below that is ignored. The default value is 10.
-
- - Variable: window-size-change-functions
- This variable holds a list of functions to be called if the size
- of any window changes for any reason. The functions are called
- just once per redisplay, and just once for each frame on which
- size changes have occurred.
-
- Each function receives the frame as its sole argument. There is no
- direct way to find out which windows changed size, or precisely
- how; however, if your size-change function keeps track, after each
- change, of the windows that interest you, you can figure out what
- has changed by comparing the old size data with the new.
-
- Creating or deleting windows counts as a size change, and therefore
- causes these functions to be called. Changing the frame size also
- counts, because it changes the sizes of the existing windows.
-
- It is not a good idea to use `save-window-excursion' in these
- functions, because that always counts as a size change, and it
- would cause these functions to be called over and over. In most
- cases, `save-selected-window' is what you need here.
-
-\1f
-File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows
-
-Window Configurations
-=====================
-
- A "window configuration" records the entire layout of a frame--all
-windows, their sizes, which buffers they contain, what part of each
-buffer is displayed, and the values of point and the mark. You can
-bring back an entire previous layout by restoring a window
-configuration previously saved.
-
- If you want to record all frames instead of just one, use a frame
-configuration instead of a window configuration. *Note Frame
-Configurations::.
-
- - Function: current-window-configuration
- This function returns a new object representing XEmacs's current
- window configuration, namely the number of windows, their sizes
- and current buffers, which window is the selected window, and for
- each window the displayed buffer, the display-start position, and
- the positions of point and the mark. An exception is made for
- point in the current buffer, whose value is not saved.
-
- - Function: set-window-configuration configuration
- This function restores the configuration of XEmacs's windows and
- buffers to the state specified by CONFIGURATION. The argument
- CONFIGURATION must be a value that was previously returned by
- `current-window-configuration'.
-
- This function always counts as a window size change and triggers
- execution of the `window-size-change-functions'. (It doesn't know
- how to tell whether the new configuration actually differs from
- the old one.)
-
- Here is a way of using this function to get the same effect as
- `save-window-excursion':
-
- (let ((config (current-window-configuration)))
- (unwind-protect
- (progn (split-window-vertically nil)
- ...)
- (set-window-configuration config)))
-
- - Special Form: save-window-excursion forms...
- This special form records the window configuration, executes FORMS
- in sequence, then restores the earlier window configuration. The
- window configuration includes the value of point and the portion
- of the buffer that is visible. It also includes the choice of
- selected window. However, it does not include the value of point
- in the current buffer; use `save-excursion' if you wish to
- preserve that.
-
- Don't use this construct when `save-selected-window' is all you
- need.
-
- Exit from `save-window-excursion' always triggers execution of the
- `window-size-change-functions'. (It doesn't know how to tell
- whether the restored configuration actually differs from the one in
- effect at the end of the FORMS.)
-
- The return value is the value of the final form in FORMS. For
- example:
-
- (split-window)
- => #<window 25 on control.texi>
- (setq w (selected-window))
- => #<window 19 on control.texi>
- (save-window-excursion
- (delete-other-windows w)
- (switch-to-buffer "foo")
- 'do-something)
- => do-something
- ;; The frame is now split again.
-
- - Function: window-configuration-p object
- This function returns `t' if OBJECT is a window configuration.
-
- Primitives to look inside of window configurations would make sense,
-but none are implemented. It is not clear they are useful enough to be
-worth implementing.
-
-\1f
-File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top
-
-Frames
-******
-
- A FRAME is a rectangle on the screen that contains one or more
-XEmacs windows. A frame initially contains a single main window (plus
-perhaps a minibuffer window), which you can subdivide vertically or
-horizontally into smaller windows.
-
- When XEmacs runs on a text-only terminal, it starts with one "TTY
-frame". If you create additional ones, XEmacs displays one and only
-one at any given time--on the terminal screen, of course.
-
- When XEmacs communicates directly with an X server, it does not have
-a TTY frame; instead, it starts with a single "X window frame". It can
-display multiple X window frames at the same time, each in its own X
-window.
-
- - Function: framep object
- This predicate returns `t' if OBJECT is a frame, and `nil'
- otherwise.
-
-* Menu:
-
-* Creating Frames:: Creating additional frames.
-* Frame Properties:: Controlling frame size, position, font, etc.
-* Frame Titles:: Automatic updating of frame titles.
-* Deleting Frames:: Frames last until explicitly deleted.
-* Finding All Frames:: How to examine all existing frames.
-* Frames and Windows:: A frame contains windows;
- display of text always works through windows.
-* Minibuffers and Frames:: How a frame finds the minibuffer to use.
-* Input Focus:: Specifying the selected frame.
-* Visibility of Frames:: Frames may be visible or invisible, or icons.
-* Raising and Lowering:: Raising a frame makes it hide other X windows;
- lowering it makes the others hide them.
-* Frame Configurations:: Saving the state of all frames.
-* Frame Hooks:: Hooks for customizing frame behavior.
-
- *Note Display::, for related information.
-
-\1f
-File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames
-
-Creating Frames
-===============
-
- To create a new frame, call the function `make-frame'.
-
- - Function: make-frame &optional props device
- This function creates a new frame on DEVICE, if DEVICE permits
- creation of frames. (An X server does; an ordinary terminal does
- not (yet).) DEVICE defaults to the selected device if omitted.
- *Note Consoles and Devices::.
-
- The argument PROPS is a property list (a list of alternating
- keyword-value specifications) of properties for the new frame. (An
- alist is accepted for backward compatibility but should not be
- passed in.) Any properties not mentioned in PROPS default
- according to the value of the variable `default-frame-plist'. For
- X devices, properties not specified in `default-frame-plist'
- default in turn from `default-x-frame-plist' and, if not specified
- there, from the X resources. For TTY devices,
- `default-tty-frame-plist' is consulted as well as
- `default-frame-plist'.
-
- The set of possible properties depends in principle on what kind of
- window system XEmacs uses to display its frames. *Note X Frame
- Properties::, for documentation of individual properties you can
- specify when creating an X window frame.
-
-\1f
-File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
-
-Frame Properties
-================
-
- A frame has many properties that control its appearance and behavior.
-Just what properties a frame has depends on which display mechanism it
-uses.
-
- Frame properties exist for the sake of window systems. A terminal
-frame has few properties, mostly for compatibility's sake; only the
-height, width and `buffer-predicate' properties really do something.
-
-* Menu:
-
-* Property Access:: How to change a frame's properties.
-* Initial Properties:: Specifying frame properties when you make a frame.
-* X Frame Properties:: List of frame properties.
-* Size and Position:: Changing the size and position of a frame.
-* Frame Name:: The name of a frame (as opposed to its title).
-
-\1f
-File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties
-
-Access to Frame Properties
---------------------------
-
- These functions let you read and change the properties of a frame.
-
- - Function: frame-properties &optional frame
- This function returns a plist listing all the properties of FRAME
- and their values.
-
- - Function: frame-property frame property &optional default
- This function returns FRAME's value for the property PROPERTY.
-
- - Function: set-frame-properties frame plist
- This function alters the properties of frame FRAME based on the
- elements of property list PLIST. If you don't mention a property
- in PLIST, its value doesn't change.
-
- - Function: set-frame-property frame prop val
- This function sets the property PROP of frame FRAME to the value
- VAL.
-
-\1f
-File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties
-
-Initial Frame Properties
-------------------------
-
- You can specify the properties for the initial startup frame by
-setting `initial-frame-plist' in your `.emacs' file.
-
- - Variable: initial-frame-plist
- This variable's value is a plist of alternating property-value
- pairs used when creating the initial X window frame.
-
- XEmacs creates the initial frame before it reads your `~/.emacs'
- file. After reading that file, XEmacs checks
- `initial-frame-plist', and applies the property settings in the
- altered value to the already created initial frame.
-
- If these settings affect the frame geometry and appearance, you'll
- see the frame appear with the wrong ones and then change to the
- specified ones. If that bothers you, you can specify the same
- geometry and appearance with X resources; those do take affect
- before the frame is created. *Note X Resources: (xemacs)Resources
- X.
-
- X resource settings typically apply to all frames. If you want to
- specify some X resources solely for the sake of the initial frame,
- and you don't want them to apply to subsequent frames, here's how
- to achieve this: specify properties in `default-frame-plist' to
- override the X resources for subsequent frames; then, to prevent
- these from affecting the initial frame, specify the same
- properties in `initial-frame-plist' with values that match the X
- resources.
-
- If these properties specify a separate minibuffer-only frame via a
-`minibuffer' property of `nil', and you have not yet created one,
-XEmacs creates one for you.
-
- - Variable: minibuffer-frame-plist
- This variable's value is a plist of properties used when creating
- an initial minibuffer-only frame--if such a frame is needed,
- according to the properties for the main initial frame.
-
- - Variable: default-frame-plist
- This is a plist specifying default values of frame properties for
- subsequent XEmacs frames (not the initial ones).
-
- See also `special-display-frame-plist', in *Note Choosing Window::.
-
- If you use options that specify window appearance when you invoke
-XEmacs, they take effect by adding elements to `default-frame-plist'.
-One exception is `-geometry', which adds the specified position to
-`initial-frame-plist' instead. *Note Command Arguments:
-(xemacs)Command Arguments.
-
-\1f
-File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties
-
-X Window Frame Properties
--------------------------
-
- Just what properties a frame has depends on what display mechanism it
-uses. Here is a table of the properties of an X window frame; of these,
-`name', `height', `width', and `buffer-predicate' provide meaningful
-information in non-X frames.
-
-`name'
- The name of the frame. Most window managers display the frame's
- name in the frame's border, at the top of the frame. If you don't
- specify a name, and you have more than one frame, XEmacs sets the
- frame name based on the buffer displayed in the frame's selected
- window.
-
- If you specify the frame name explicitly when you create the
- frame, the name is also used (instead of the name of the XEmacs
- executable) when looking up X resources for the frame.
-
-`display'
- The display on which to open this frame. It should be a string of
- the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
- variable.
-
-`left'
- The screen position of the left edge, in pixels, with respect to
- the left edge of the screen. The value may be a positive number
- POS, or a list of the form `(+ POS)' which permits specifying a
- negative POS value.
-
- A negative number -POS, or a list of the form `(- POS)', actually
- specifies the position of the right edge of the window with
- respect to the right edge of the screen. A positive value of POS
- counts toward the left. If the property is a negative integer
- -POS then POS is positive!
-
-`top'
- The screen position of the top edge, in pixels, with respect to the
- top edge of the screen. The value may be a positive number POS,
- or a list of the form `(+ POS)' which permits specifying a
- negative POS value.
-
- A negative number -POS, or a list of the form `(- POS)', actually
- specifies the position of the bottom edge of the window with
- respect to the bottom edge of the screen. A positive value of POS
- counts toward the top. If the property is a negative integer -POS
- then POS is positive!
-
-`icon-left'
- The screen position of the left edge _of the frame's icon_, in
- pixels, counting from the left edge of the screen. This takes
- effect if and when the frame is iconified.
-
-`icon-top'
- The screen position of the top edge _of the frame's icon_, in
- pixels, counting from the top edge of the screen. This takes
- effect if and when the frame is iconified.
-
-`user-position'
- Non-`nil' if the screen position of the frame was explicitly
- requested by the user (for example, with the `-geometry' option).
- Nothing automatically makes this property non-`nil'; it is up to
- Lisp programs that call `make-frame' to specify this property as
- well as specifying the `left' and `top' properties.
-
-`height'
- The height of the frame contents, in characters. (To get the
- height in pixels, call `frame-pixel-height'; see *Note Size and
- Position::.)
-
-`width'
- The width of the frame contents, in characters. (To get the
- height in pixels, call `frame-pixel-width'; see *Note Size and
- Position::.)
-
-`window-id'
- The number of the X window for the frame.
-
-`minibuffer'
- Whether this frame has its own minibuffer. The value `t' means
- yes, `nil' means no, `only' means this frame is just a minibuffer.
- If the value is a minibuffer window (in some other frame), the
- new frame uses that minibuffer. (Minibuffer-only and
- minibuffer-less frames are not yet implemented in XEmacs.)
-
-`buffer-predicate'
- The buffer-predicate function for this frame. The function
- `other-buffer' uses this predicate (from the selected frame) to
- decide which buffers it should consider, if the predicate is not
- `nil'. It calls the predicate with one arg, a buffer, once for
- each buffer; if the predicate returns a non-`nil' value, it
- considers that buffer.
-
-`scroll-bar-width'
- The width of the vertical scroll bar, in pixels.
-
-`cursor-color'
- The color for the cursor that shows point.
-
-`border-color'
- The color for the border of the frame.
-
-`border-width'
- The width in pixels of the window border.
-
-`internal-border-width'
- The distance in pixels between text and border.
-
-`unsplittable'
- If non-`nil', this frame's window is never split automatically.
-
-`inter-line-space'
- The space in pixels between adjacent lines of text. (Not currently
- implemented.)
-
-`modeline'
- Whether the frame has a modeline.
-
-\1f
-File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties
-
-Frame Size And Position
------------------------
-
- You can read or change the size and position of a frame using the
-frame properties `left', `top', `height', and `width'. Whatever
-geometry properties you don't specify are chosen by the window manager
-in its usual fashion.
-
- Here are some special features for working with sizes and positions:
-
- - Function: set-frame-position frame left top
- This function sets the position of the top left corner of FRAME to
- LEFT and TOP. These arguments are measured in pixels, and count
- from the top left corner of the screen. Negative property values
- count up or rightward from the top left corner of the screen.
-
- - Function: frame-height &optional frame
- - Function: frame-width &optional frame
- These functions return the height and width of FRAME, measured in
- lines and columns. If you don't supply FRAME, they use the
- selected frame.
-
- - Function: frame-pixel-height &optional frame
- - Function: frame-pixel-width &optional frame
- These functions return the height and width of FRAME, measured in
- pixels. If you don't supply FRAME, they use the selected frame.
-
- - Function: set-frame-size frame cols rows &optional pretend
- This function sets the size of FRAME, measured in characters; COLS
- and ROWS specify the new width and height. (If PRETEND is
- non-nil, it means that redisplay should act as if the frame's size
- is COLS by ROWS, but the actual size of the frame should not be
- changed. You should not normally use this option.)
-
- You can also use the functions `set-frame-height' and
-`set-frame-width' to set the height and width individually. The frame
-is the first argument and the size (in rows or columns) is the second.
-(There is an optional third argument, PRETEND, which has the same
-purpose as the corresponding argument in `set-frame-size'.)
-
-\1f
-File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties
-
-The Name of a Frame (As Opposed to Its Title)
----------------------------------------------
-
- Under X, every frame has a name, which is not the same as the title
-of the frame. A frame's name is used to look up its resources and does
-not normally change over the lifetime of a frame. It is perfectly
-allowable, and quite common, for multiple frames to have the same name.
-
- - Function: frame-name &optional frame
- This function returns the name of FRAME, which defaults to the
- selected frame if not specified. The name of a frame can also be
- obtained from the frame's properties. *Note Frame Properties::.
-
- - Variable: default-frame-name
- This variable holds the default name to assign to newly-created
- frames. This can be overridden by arguments to `make-frame'. This
- must be a string.
-
-\1f
-File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
-
-Frame Titles
-============
-
- Every frame has a title; most window managers display the frame
-title at the top of the frame. You can specify an explicit title with
-the `name' frame property. But normally you don't specify this
-explicitly, and XEmacs computes the title automatically.
-
- XEmacs computes the frame title based on a template stored in the
-variable `frame-title-format'.
-
- - Variable: frame-title-format
- This variable specifies how to compute a title for a frame when
- you have not explicitly specified one.
-
- The variable's value is actually a modeline construct, just like
- `modeline-format'. *Note Modeline Data::.
-
- - Variable: frame-icon-title-format
- This variable specifies how to compute the title for an iconified
- frame, when you have not explicitly specified the frame title.
- This title appears in the icon itself.
-
- - Function: x-set-frame-icon-pixmap frame pixmap &optional mask
- This function sets the icon of the given frame to the given image
- instance, which should be an image instance object (as returned by
- `make-image-instance'), a glyph object (as returned by
- `make-glyph'), or `nil'. If a glyph object is given, the glyph
- will be instantiated on the frame to produce an image instance
- object.
-
- If the given image instance has a mask, that will be used as the
- icon mask; however, not all window managers support this.
-
- The window manager is also not required to support color pixmaps,
- only bitmaps (one plane deep).
-
- If the image instance does not have a mask, then the optional
- third argument may be the image instance to use as the mask (it
- must be one plane deep). *Note Glyphs::.
-
-\1f
-File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
-
-Deleting Frames
-===============
-
- Frames remain potentially visible until you explicitly "delete"
-them. A deleted frame cannot appear on the screen, but continues to
-exist as a Lisp object until there are no references to it.
-
- - Command: delete-frame &optional frame
- This function deletes the frame FRAME. By default, FRAME is the
- selected frame.
-
- - Function: frame-live-p frame
- The function `frame-live-p' returns non-`nil' if the frame FRAME
- has not been deleted.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows
+
+Changing the Size of a Window
+=============================
+
+ The window size functions fall into two classes: high-level commands
+that change the size of windows and low-level functions that access
+window size. XEmacs does not permit overlapping windows or gaps between
+windows, so resizing one window affects other windows.
+
+ - Command: enlarge-window size &optional horizontal window
+ This function makes the selected window SIZE lines taller,
+ stealing lines from neighboring windows. It takes the lines from
+ one window at a time until that window is used up, then takes from
+ another. If a window from which lines are stolen shrinks below
+ `window-min-height' lines, that window disappears.
+
+ If HORIZONTAL is non-`nil', this function makes WINDOW wider by
+ SIZE columns, stealing columns instead of lines. If a window from
+ which columns are stolen shrinks below `window-min-width' columns,
+ that window disappears.
+
+ If the requested size would exceed that of the window's frame,
+ then the function makes the window occupy the entire height (or
+ width) of the frame.
+
+ If SIZE is negative, this function shrinks the window by -SIZE
+ lines or columns. If that makes the window smaller than the
+ minimum size (`window-min-height' and `window-min-width'),
+ `enlarge-window' deletes the window.
+
+ If WINDOW is non-`nil', it specifies a window to change instead of
+ the selected window.
+
+ `enlarge-window' returns `nil'.
+
+ - Command: enlarge-window-horizontally columns
+ This function makes the selected window COLUMNS wider. It could
+ be defined as follows:
+
+ (defun enlarge-window-horizontally (columns)
+ (enlarge-window columns t))
+
+ - Command: enlarge-window-pixels count &optional side window
+ This function makes the selected window COUNT pixels larger. When
+ called from Lisp, optional second argument SIDE non-`nil' means to
+ grow sideways COUNT pixels, and optional third argument WINDOW
+ specifies the window to change instead of the selected window.
+
+ - Command: shrink-window size &optional horizontal window
+ This function is like `enlarge-window' but negates the argument
+ SIZE, making the selected window smaller by giving lines (or
+ columns) to the other windows. If the window shrinks below
+ `window-min-height' or `window-min-width', then it disappears.
+
+ If SIZE is negative, the window is enlarged by -SIZE lines or
+ columns.
+
+ If WINDOW is non-`nil', it specifies a window to change instead of
+ the selected window.
+
+ - Command: shrink-window-horizontally columns
+ This function makes the selected window COLUMNS narrower. It
+ could be defined as follows:
+
+ (defun shrink-window-horizontally (columns)
+ (shrink-window columns t))
+
+ - Command: shrink-window-pixels count &optional side window
+ This function makes the selected window COUNT pixels smaller.
+ When called from Lisp, optional second argument SIDE non-`nil'
+ means to shrink sideways COUNT pixels, and optional third argument
+ WINDOW specifies the window to change instead of the selected
+ window.
+
+ The following two variables constrain the window-size-changing
+functions to a minimum height and width.
+
+ - User Option: window-min-height
+ The value of this variable determines how short a window may become
+ before it is automatically deleted. Making a window smaller than
+ `window-min-height' automatically deletes it, and no window may be
+ created shorter than this. The absolute minimum height is two
+ (allowing one line for the mode line, and one line for the buffer
+ display). Actions that change window sizes reset this variable to
+ two if it is less than two. The default value is 4.
+
+ - User Option: window-min-width
+ The value of this variable determines how narrow a window may
+ become before it automatically deleted. Making a window smaller
+ than `window-min-width' automatically deletes it, and no window
+ may be created narrower than this. The absolute minimum width is
+ one; any value below that is ignored. The default value is 10.
+
+ - Variable: window-size-change-functions
+ This variable holds a list of functions to be called if the size
+ of any window changes for any reason. The functions are called
+ just once per redisplay, and just once for each frame on which
+ size changes have occurred.
+
+ Each function receives the frame as its sole argument. There is no
+ direct way to find out which windows changed size, or precisely
+ how; however, if your size-change function keeps track, after each
+ change, of the windows that interest you, you can figure out what
+ has changed by comparing the old size data with the new.
+
+ Creating or deleting windows counts as a size change, and therefore
+ causes these functions to be called. Changing the frame size also
+ counts, because it changes the sizes of the existing windows.
+
+ It is not a good idea to use `save-window-excursion' in these
+ functions, because that always counts as a size change, and it
+ would cause these functions to be called over and over. In most
+ cases, `save-selected-window' is what you need here.
+
+\1f
+File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows
+
+Window Configurations
+=====================
+
+ A "window configuration" records the entire layout of a frame--all
+windows, their sizes, which buffers they contain, what part of each
+buffer is displayed, and the values of point and the mark. You can
+bring back an entire previous layout by restoring a window
+configuration previously saved.
+
+ If you want to record all frames instead of just one, use a frame
+configuration instead of a window configuration. *Note Frame
+Configurations::.
+
+ - Function: current-window-configuration
+ This function returns a new object representing XEmacs's current
+ window configuration, namely the number of windows, their sizes
+ and current buffers, which window is the selected window, and for
+ each window the displayed buffer, the display-start position, and
+ the positions of point and the mark. An exception is made for
+ point in the current buffer, whose value is not saved.
+
+ - Function: set-window-configuration configuration
+ This function restores the configuration of XEmacs's windows and
+ buffers to the state specified by CONFIGURATION. The argument
+ CONFIGURATION must be a value that was previously returned by
+ `current-window-configuration'.
+
+ This function always counts as a window size change and triggers
+ execution of the `window-size-change-functions'. (It doesn't know
+ how to tell whether the new configuration actually differs from
+ the old one.)
+
+ Here is a way of using this function to get the same effect as
+ `save-window-excursion':
+
+ (let ((config (current-window-configuration)))
+ (unwind-protect
+ (progn (split-window-vertically nil)
+ ...)
+ (set-window-configuration config)))
+
+ - Special Form: save-window-excursion forms...
+ This special form records the window configuration, executes FORMS
+ in sequence, then restores the earlier window configuration. The
+ window configuration includes the value of point and the portion
+ of the buffer that is visible. It also includes the choice of
+ selected window. However, it does not include the value of point
+ in the current buffer; use `save-excursion' if you wish to
+ preserve that.
+
+ Don't use this construct when `save-selected-window' is all you
+ need.
+
+ Exit from `save-window-excursion' always triggers execution of the
+ `window-size-change-functions'. (It doesn't know how to tell
+ whether the restored configuration actually differs from the one in
+ effect at the end of the FORMS.)
+
+ The return value is the value of the final form in FORMS. For
+ example:
+
+ (split-window)
+ => #<window 25 on control.texi>
+ (setq w (selected-window))
+ => #<window 19 on control.texi>
+ (save-window-excursion
+ (delete-other-windows w)
+ (switch-to-buffer "foo")
+ 'do-something)
+ => do-something
+ ;; The frame is now split again.
+
+ - Function: window-configuration-p object
+ This function returns `t' if OBJECT is a window configuration.
+
+ Primitives to look inside of window configurations would make sense,
+but none are implemented. It is not clear they are useful enough to be
+worth implementing.
+
+\1f
+File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top
+
+Frames
+******
+
+ A FRAME is a rectangle on the screen that contains one or more
+XEmacs windows (*note Windows::). A frame initially contains a single
+main window (plus perhaps an echo area), which you can subdivide
+vertically or horizontally into smaller windows. Each window is
+associated with a modeline (*note Modeline Format::), and optionally two
+scrollbars (*note Scrollbars::). By default the vertical scrollbar is
+on, the horizontal scrollbar is off.
+
+ The frame may also contain menubars (*note Menubar::), toolbars
+(*note Toolbar Intro::), and gutters (*note Gutter Intro::). By default
+there is one of each at the top of the frame, with menubar topmost,
+toolbar next, and gutter lowest, immediately above the windows.
+(Warning: the gutter is a new, experimental, and unstable feature of
+XEmacs version 21.2.)
+
+ When XEmacs runs on a text-only terminal, it starts with one "TTY
+frame". If you create additional ones, XEmacs displays one and only
+one at any given time--on the terminal screen, of course.
+
+ When XEmacs communicates directly with an X server, it does not have
+a TTY frame; instead, it starts with a single "X window frame". It can
+display multiple X window frames at the same time, each in its own X
+window.
+
+ - Function: framep object
+ This predicate returns `t' if OBJECT is a frame, and `nil'
+ otherwise.
+
+* Menu:
+
+* Creating Frames:: Creating additional frames.
+* Frame Properties:: Controlling frame size, position, font, etc.
+* Frame Titles:: Automatic updating of frame titles.
+* Deleting Frames:: Frames last until explicitly deleted.
+* Finding All Frames:: How to examine all existing frames.
+* Frames and Windows:: A frame contains windows;
+ display of text always works through windows.
+* Minibuffers and Frames:: How a frame finds the minibuffer to use.
+* Input Focus:: Specifying the selected frame.
+* Visibility of Frames:: Frames may be visible or invisible, or icons.
+* Raising and Lowering:: Raising a frame makes it hide other X windows;
+ lowering it makes the others hide them.
+* Frame Configurations:: Saving the state of all frames.
+* Frame Hooks:: Hooks for customizing frame behavior.
+
+ *Note Display::, for related information.
+
+\1f
+File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames
+
+Creating Frames
+===============
+
+ To create a new frame, call the function `make-frame'.
+
+ - Function: make-frame &optional props device
+ This function creates a new frame on DEVICE, if DEVICE permits
+ creation of frames. (An X server does; an ordinary terminal does
+ not (yet).) DEVICE defaults to the selected device if omitted.
+ *Note Consoles and Devices::.
+
+ The argument PROPS is a property list (a list of alternating
+ keyword-value specifications) of properties for the new frame. (An
+ alist is accepted for backward compatibility but should not be
+ passed in.) Any properties not mentioned in PROPS default
+ according to the value of the variable `default-frame-plist'. For
+ X devices, properties not specified in `default-frame-plist'
+ default in turn from `default-x-frame-plist' and, if not specified
+ there, from the X resources. For TTY devices,
+ `default-tty-frame-plist' is consulted as well as
+ `default-frame-plist'.
+
+ The set of possible properties depends in principle on what kind of
+ window system XEmacs uses to display its frames. *Note X Frame
+ Properties::, for documentation of individual properties you can
+ specify when creating an X window frame.
+
+\1f
+File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
+
+Frame Properties
+================
+
+ A frame has many properties that control its appearance and behavior.
+Just what properties a frame has depends on which display mechanism it
+uses.
+
+ Frame properties exist for the sake of window systems. A terminal
+frame has few properties, mostly for compatibility's sake; only the
+height, width and `buffer-predicate' properties really do something.
+
+* Menu:
+
+* Property Access:: How to change a frame's properties.
+* Initial Properties:: Specifying frame properties when you make a frame.
+* X Frame Properties:: List of frame properties.
+* Size and Position:: Changing the size and position of a frame.
+* Frame Name:: The name of a frame (as opposed to its title).
+
+\1f
+File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties
+
+Access to Frame Properties
+--------------------------
+
+ These functions let you read and change the properties of a frame.
+
+ - Function: frame-properties &optional frame
+ This function returns a plist listing all the properties of FRAME
+ and their values.
+
+ - Function: frame-property frame property &optional default
+ This function returns FRAME's value for the property PROPERTY.
+
+ - Function: set-frame-properties frame plist
+ This function alters the properties of frame FRAME based on the
+ elements of property list PLIST. If you don't mention a property
+ in PLIST, its value doesn't change.
+
+ - Function: set-frame-property frame prop val
+ This function sets the property PROP of frame FRAME to the value
+ VAL.
+
+\1f
+File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties
+
+Initial Frame Properties
+------------------------
+
+ You can specify the properties for the initial startup frame by
+setting `initial-frame-plist' in your `.emacs' file.
+
+ - Variable: initial-frame-plist
+ This variable's value is a plist of alternating property-value
+ pairs used when creating the initial X window frame.
+
+ XEmacs creates the initial frame before it reads your `~/.emacs'
+ file. After reading that file, XEmacs checks
+ `initial-frame-plist', and applies the property settings in the
+ altered value to the already created initial frame.
+
+ If these settings affect the frame geometry and appearance, you'll
+ see the frame appear with the wrong ones and then change to the
+ specified ones. If that bothers you, you can specify the same
+ geometry and appearance with X resources; those do take affect
+ before the frame is created. *Note X Resources: (xemacs)Resources
+ X.
+
+ X resource settings typically apply to all frames. If you want to
+ specify some X resources solely for the sake of the initial frame,
+ and you don't want them to apply to subsequent frames, here's how
+ to achieve this: specify properties in `default-frame-plist' to
+ override the X resources for subsequent frames; then, to prevent
+ these from affecting the initial frame, specify the same
+ properties in `initial-frame-plist' with values that match the X
+ resources.
+
+ If these properties specify a separate minibuffer-only frame via a
+`minibuffer' property of `nil', and you have not yet created one,
+XEmacs creates one for you.
+
+ - Variable: minibuffer-frame-plist
+ This variable's value is a plist of properties used when creating
+ an initial minibuffer-only frame--if such a frame is needed,
+ according to the properties for the main initial frame.
+
+ - Variable: default-frame-plist
+ This is a plist specifying default values of frame properties for
+ subsequent XEmacs frames (not the initial ones).
+
+ See also `special-display-frame-plist', in *Note Choosing Window::.
+
+ If you use options that specify window appearance when you invoke
+XEmacs, they take effect by adding elements to `default-frame-plist'.
+One exception is `-geometry', which adds the specified position to
+`initial-frame-plist' instead. *Note Command Arguments:
+(xemacs)Command Arguments.
+
+\1f
+File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties
+
+X Window Frame Properties
+-------------------------
+
+ Just what properties a frame has depends on what display mechanism it
+uses. Here is a table of the properties of an X window frame; of these,
+`name', `height', `width', and `buffer-predicate' provide meaningful
+information in non-X frames.
+
+`name'
+ The name of the frame. Most window managers display the frame's
+ name in the frame's border, at the top of the frame. If you don't
+ specify a name, and you have more than one frame, XEmacs sets the
+ frame name based on the buffer displayed in the frame's selected
+ window.
+
+ If you specify the frame name explicitly when you create the
+ frame, the name is also used (instead of the name of the XEmacs
+ executable) when looking up X resources for the frame.
+
+`display'
+ The display on which to open this frame. It should be a string of
+ the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
+ variable.
+
+`left'
+ The screen position of the left edge, in pixels, with respect to
+ the left edge of the screen. The value may be a positive number
+ POS, or a list of the form `(+ POS)' which permits specifying a
+ negative POS value.
+
+ A negative number -POS, or a list of the form `(- POS)', actually
+ specifies the position of the right edge of the window with
+ respect to the right edge of the screen. A positive value of POS
+ counts toward the left. If the property is a negative integer
+ -POS then POS is positive!
+
+`top'
+ The screen position of the top edge, in pixels, with respect to the
+ top edge of the screen. The value may be a positive number POS,
+ or a list of the form `(+ POS)' which permits specifying a
+ negative POS value.
+
+ A negative number -POS, or a list of the form `(- POS)', actually
+ specifies the position of the bottom edge of the window with
+ respect to the bottom edge of the screen. A positive value of POS
+ counts toward the top. If the property is a negative integer -POS
+ then POS is positive!
+
+`icon-left'
+ The screen position of the left edge _of the frame's icon_, in
+ pixels, counting from the left edge of the screen. This takes
+ effect if and when the frame is iconified.
+
+`icon-top'
+ The screen position of the top edge _of the frame's icon_, in
+ pixels, counting from the top edge of the screen. This takes
+ effect if and when the frame is iconified.
+
+`user-position'
+ Non-`nil' if the screen position of the frame was explicitly
+ requested by the user (for example, with the `-geometry' option).
+ Nothing automatically makes this property non-`nil'; it is up to
+ Lisp programs that call `make-frame' to specify this property as
+ well as specifying the `left' and `top' properties.
+
+`height'
+ The height of the frame contents, in characters. (To get the
+ height in pixels, call `frame-pixel-height'; see *Note Size and
+ Position::.)
+
+`width'
+ The width of the frame contents, in characters. (To get the
+ height in pixels, call `frame-pixel-width'; see *Note Size and
+ Position::.)
+
+`window-id'
+ The number of the X window for the frame.
+
+`minibuffer'
+ Whether this frame has its own minibuffer. The value `t' means
+ yes, `nil' means no, `only' means this frame is just a minibuffer.
+ If the value is a minibuffer window (in some other frame), the
+ new frame uses that minibuffer. (Minibuffer-only and
+ minibuffer-less frames are not yet implemented in XEmacs.)
+
+`buffer-predicate'
+ The buffer-predicate function for this frame. The function
+ `other-buffer' uses this predicate (from the selected frame) to
+ decide which buffers it should consider, if the predicate is not
+ `nil'. It calls the predicate with one arg, a buffer, once for
+ each buffer; if the predicate returns a non-`nil' value, it
+ considers that buffer.
+
+`scroll-bar-width'
+ The width of the vertical scroll bar, in pixels.
+
+`cursor-color'
+ The color for the cursor that shows point.
+
+`border-color'
+ The color for the border of the frame.
+
+`border-width'
+ The width in pixels of the window border.
+
+`internal-border-width'
+ The distance in pixels between text and border.
+
+`unsplittable'
+ If non-`nil', this frame's window is never split automatically.
+
+`inter-line-space'
+ The space in pixels between adjacent lines of text. (Not currently
+ implemented.)
+
+`modeline'
+ Whether the frame has a modeline.
+
+\1f
+File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties
+
+Frame Size And Position
+-----------------------
+
+ You can read or change the size and position of a frame using the
+frame properties `left', `top', `height', and `width'. Whatever
+geometry properties you don't specify are chosen by the window manager
+in its usual fashion.
+
+ Here are some special features for working with sizes and positions:
+
+ - Function: set-frame-position frame left top
+ This function sets the position of the top left corner of FRAME to
+ LEFT and TOP. These arguments are measured in pixels, and count
+ from the top left corner of the screen. Negative property values
+ count up or rightward from the top left corner of the screen.
+
+ - Function: frame-height &optional frame
+ - Function: frame-width &optional frame
+ These functions return the height and width of FRAME, measured in
+ lines and columns. If you don't supply FRAME, they use the
+ selected frame.
+
+ - Function: frame-pixel-height &optional frame
+ - Function: frame-pixel-width &optional frame
+ These functions return the height and width of FRAME, measured in
+ pixels. If you don't supply FRAME, they use the selected frame.
+
+ - Function: set-frame-size frame cols rows &optional pretend
+ This function sets the size of FRAME, measured in characters; COLS
+ and ROWS specify the new width and height. (If PRETEND is
+ non-nil, it means that redisplay should act as if the frame's size
+ is COLS by ROWS, but the actual size of the frame should not be
+ changed. You should not normally use this option.)
+
+ You can also use the functions `set-frame-height' and
+`set-frame-width' to set the height and width individually. The frame
+is the first argument and the size (in rows or columns) is the second.
+(There is an optional third argument, PRETEND, which has the same
+purpose as the corresponding argument in `set-frame-size'.)
+
+\1f
+File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties
+
+The Name of a Frame (As Opposed to Its Title)
+---------------------------------------------
+
+ Under X, every frame has a name, which is not the same as the title
+of the frame. A frame's name is used to look up its resources and does
+not normally change over the lifetime of a frame. It is perfectly
+allowable, and quite common, for multiple frames to have the same name.
+
+ - Function: frame-name &optional frame
+ This function returns the name of FRAME, which defaults to the
+ selected frame if not specified. The name of a frame can also be
+ obtained from the frame's properties. *Note Frame Properties::.
+
+ - Variable: default-frame-name
+ This variable holds the default name to assign to newly-created
+ frames. This can be overridden by arguments to `make-frame'. This
+ must be a string.
+
+\1f
+File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
+
+Frame Titles
+============
+
+ Every frame has a title; most window managers display the frame
+title at the top of the frame. You can specify an explicit title with
+the `name' frame property. But normally you don't specify this
+explicitly, and XEmacs computes the title automatically.
+
+ XEmacs computes the frame title based on a template stored in the
+variable `frame-title-format'.
+
+ - Variable: frame-title-format
+ This variable specifies how to compute a title for a frame when
+ you have not explicitly specified one.
+
+ The variable's value is actually a modeline construct, just like
+ `modeline-format'. *Note Modeline Data::.
+
+ - Variable: frame-icon-title-format
+ This variable specifies how to compute the title for an iconified
+ frame, when you have not explicitly specified the frame title.
+ This title appears in the icon itself.
+
+ - Function: x-set-frame-icon-pixmap frame pixmap &optional mask
+ This function sets the icon of the given frame to the given image
+ instance, which should be an image instance object (as returned by
+ `make-image-instance'), a glyph object (as returned by
+ `make-glyph'), or `nil'. If a glyph object is given, the glyph
+ will be instantiated on the frame to produce an image instance
+ object.
+
+ If the given image instance has a mask, that will be used as the
+ icon mask; however, not all window managers support this.
+
+ The window manager is also not required to support color pixmaps,
+ only bitmaps (one plane deep).
+
+ If the image instance does not have a mask, then the optional
+ third argument may be the image instance to use as the mask (it
+ must be one plane deep). *Note Glyphs::.
+
+\1f
+File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
+
+Deleting Frames
+===============
+
+ Frames remain potentially visible until you explicitly "delete"
+them. A deleted frame cannot appear on the screen, but continues to
+exist as a Lisp object until there are no references to it.
+
+ - Command: delete-frame &optional frame
+ This function deletes the frame FRAME. By default, FRAME is the
+ selected frame.
+
+ - Function: frame-live-p frame
+ The function `frame-live-p' returns non-`nil' if the frame FRAME
+ has not been deleted.
+
+\1f
File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
Finding All Frames
This function returns the X display which DEVICE is connected to,
if DEVICE is an X device.
-\1f
-File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices
-
-The Selected Console and Device
-===============================
-
- - Function: select-console console
- This function selects the console CONSOLE. Subsequent editing
- commands apply to its selected device, selected frame, and selected
- window. The selection of CONSOLE lasts until the next time the
- user does something to select a different console, or until the
- next time this function is called.
-
- - Function: selected-console
- This function returns the console which is currently active.
-
- - Function: select-device device
- This function selects the device DEVICE.
-
- - Function: selected-device &optional console
- This function returns the device which is currently active. If
- optional CONSOLE is non-`nil', this function returns the device
- that would be currently active if CONSOLE were the selected
- console.
-
-\1f
-File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
-
-Console and Device I/O
-======================
-
- - Function: console-disable-input console
- This function disables input on console CONSOLE.
-
- - Function: console-enable-input console
- This function enables input on console CONSOLE.
-
- Each device has a "baud rate" value associated with it. On most
-systems, changing this value will affect the amount of padding and
-other strategic decisions made during redisplay.
-
- - Function: device-baud-rate &optional device
- This function returns the output baud rate of DEVICE.
-
- - Function: set-device-baud-rate device rate
- This function sets the output baud rate of DEVICE to RATE.
-
-\1f
-File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
-
-Positions
-*********
-
- A "position" is the index of a character in the text of a buffer.
-More precisely, a position identifies the place between two characters
-(or before the first character, or after the last character), so we can
-speak of the character before or after a given position. However, we
-often speak of the character "at" a position, meaning the character
-after that position.
-
- Positions are usually represented as integers starting from 1, but
-can also be represented as "markers"--special objects that relocate
-automatically when text is inserted or deleted so they stay with the
-surrounding characters. *Note Markers::.
-
-* Menu:
-
-* Point:: The special position where editing takes place.
-* Motion:: Changing point.
-* Excursions:: Temporary motion and buffer changes.
-* Narrowing:: Restricting editing to a portion of the buffer.
-
-\1f
-File: lispref.info, Node: Point, Next: Motion, Up: Positions
-
-Point
-=====
-
- "Point" is a special buffer position used by many editing commands,
-including the self-inserting typed characters and text insertion
-functions. Other commands move point through the text to allow editing
-and insertion at different places.
-
- Like other positions, point designates a place between two characters
-(or before the first character, or after the last character), rather
-than a particular character. Usually terminals display the cursor over
-the character that immediately follows point; point is actually before
-the character on which the cursor sits.
-
- The value of point is a number between 1 and the buffer size plus 1.
-If narrowing is in effect (*note Narrowing::), then point is constrained
-to fall within the accessible portion of the buffer (possibly at one end
-of it).
-
- Each buffer has its own value of point, which is independent of the
-value of point in other buffers. Each window also has a value of point,
-which is independent of the value of point in other windows on the same
-buffer. This is why point can have different values in various windows
-that display the same buffer. When a buffer appears in only one window,
-the buffer's point and the window's point normally have the same value,
-so the distinction is rarely important. *Note Window Point::, for more
-details.
-
- - Function: point &optional buffer
- This function returns the value of point in BUFFER, as an integer.
- BUFFER defaults to the current buffer if omitted.
-
- (point)
- => 175
-
- - Function: point-min &optional buffer
- This function returns the minimum accessible value of point in
- BUFFER. This is normally 1, but if narrowing is in effect, it is
- the position of the start of the region that you narrowed to.
- (*Note Narrowing::.) BUFFER defaults to the current buffer if
- omitted.
-
- - Function: point-max &optional buffer
- This function returns the maximum accessible value of point in
- BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
- in effect, in which case it is the position of the end of the
- region that you narrowed to. (*note Narrowing::). BUFFER defaults
- to the current buffer if omitted.
-
- - Function: buffer-end flag &optional buffer
- This function returns `(point-min buffer)' if FLAG is less than 1,
- `(point-max buffer)' otherwise. The argument FLAG must be a
- number. BUFFER defaults to the current buffer if omitted.
-
- - Function: buffer-size &optional buffer
- This function returns the total number of characters in BUFFER.
- In the absence of any narrowing (*note Narrowing::), `point-max'
- returns a value one larger than this. BUFFER defaults to the
- current buffer if omitted.
-
- (buffer-size)
- => 35
- (point-max)
- => 36
-
- - Variable: buffer-saved-size
- The value of this buffer-local variable is the former length of the
- current buffer, as of the last time it was read in, saved or
- auto-saved.
-
-\1f
-File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
-
-Motion
-======
-
- Motion functions change the value of point, either relative to the
-current value of point, relative to the beginning or end of the buffer,
-or relative to the edges of the selected window. *Note Point::.
-
-* Menu:
-
-* Character Motion:: Moving in terms of characters.
-* Word Motion:: Moving in terms of words.
-* Buffer End Motion:: Moving to the beginning or end of the buffer.
-* Text Lines:: Moving in terms of lines of text.
-* Screen Lines:: Moving in terms of lines as displayed.
-* List Motion:: Moving by parsing lists and sexps.
-* Skipping Characters:: Skipping characters belonging to a certain set.
-
-\1f
-File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
-
-Motion by Characters
---------------------
-
- These functions move point based on a count of characters.
-`goto-char' is the fundamental primitive; the other functions use that.
-
- - Command: goto-char position &optional buffer
- This function sets point in `buffer' to the value POSITION. If
- POSITION is less than 1, it moves point to the beginning of the
- buffer. If POSITION is greater than the length of the buffer, it
- moves point to the end. BUFFER defaults to the current buffer if
- omitted.
-
- If narrowing is in effect, POSITION still counts from the
- beginning of the buffer, but point cannot go outside the accessible
- portion. If POSITION is out of range, `goto-char' moves point to
- the beginning or the end of the accessible portion.
-
- When this function is called interactively, POSITION is the
- numeric prefix argument, if provided; otherwise it is read from the
- minibuffer.
-
- `goto-char' returns POSITION.
-
- - Command: forward-char &optional count buffer
- This function moves point COUNT characters forward, towards the
- end of the buffer (or backward, towards the beginning of the
- buffer, if COUNT is negative). If the function attempts to move
- point past the beginning or end of the buffer (or the limits of
- the accessible portion, when narrowing is in effect), an error is
- signaled with error code `beginning-of-buffer' or `end-of-buffer'.
- BUFFER defaults to the current buffer if omitted.
-
- In an interactive call, COUNT is the numeric prefix argument.
-
- - Command: backward-char &optional count buffer
- This function moves point COUNT characters backward, towards the
- beginning of the buffer (or forward, towards the end of the
- buffer, if COUNT is negative). If the function attempts to move
- point past the beginning or end of the buffer (or the limits of
- the accessible portion, when narrowing is in effect), an error is
- signaled with error code `beginning-of-buffer' or `end-of-buffer'.
- BUFFER defaults to the current buffer if omitted.
-
- In an interactive call, COUNT is the numeric prefix argument.
-
-\1f
-File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
-
-Motion by Words
----------------
-
- These functions for parsing words use the syntax table to decide
-whether a given character is part of a word. *Note Syntax Tables::.
-
- - Command: forward-word count &optional buffer
- This function moves point forward COUNT words (or backward if
- COUNT is negative). Normally it returns `t'. If this motion
- encounters the beginning or end of the buffer, or the limits of the
- accessible portion when narrowing is in effect, point stops there
- and the value is `nil'. BUFFER defaults to the current buffer if
- omitted.
-
- In an interactive call, COUNT is set to the numeric prefix
- argument.
-
- - Command: backward-word count &optional buffer
- This function is just like `forward-word', except that it moves
- backward until encountering the front of a word, rather than
- forward. BUFFER defaults to the current buffer if omitted.
-
- In an interactive call, COUNT is set to the numeric prefix
- argument.
-
- This function is rarely used in programs, as it is more efficient
- to call `forward-word' with a negative argument.
-
- - Variable: words-include-escapes
- This variable affects the behavior of `forward-word' and everything
- that uses it. If it is non-`nil', then characters in the "escape"
- and "character quote" syntax classes count as part of words.
- Otherwise, they do not.
-
-\1f
-File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
-
-Motion to an End of the Buffer
-------------------------------
-
- To move point to the beginning of the buffer, write:
-
- (goto-char (point-min))
-
-Likewise, to move to the end of the buffer, use:
-
- (goto-char (point-max))
-
- Here are two commands that users use to do these things. They are
-documented here to warn you not to use them in Lisp programs, because
-they set the mark and display messages in the echo area.
-
- - Command: beginning-of-buffer &optional n
- This function moves point to the beginning of the buffer (or the
- limits of the accessible portion, when narrowing is in effect),
- setting the mark at the previous position. If N is non-`nil',
- then it puts point N tenths of the way from the beginning of the
- buffer.
-
- In an interactive call, N is the numeric prefix argument, if
- provided; otherwise N defaults to `nil'.
-
- Don't use this function in Lisp programs!
-
- - Command: end-of-buffer &optional n
- This function moves point to the end of the buffer (or the limits
- of the accessible portion, when narrowing is in effect), setting
- the mark at the previous position. If N is non-`nil', then it puts
- point N tenths of the way from the end of the buffer.
-
- In an interactive call, N is the numeric prefix argument, if
- provided; otherwise N defaults to `nil'.
-
- Don't use this function in Lisp programs!
-
-\1f
-File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
-
-Motion by Text Lines
---------------------
-
- Text lines are portions of the buffer delimited by newline
-characters, which are regarded as part of the previous line. The first
-text line begins at the beginning of the buffer, and the last text line
-ends at the end of the buffer whether or not the last character is a
-newline. The division of the buffer into text lines is not affected by
-the width of the window, by line continuation in display, or by how
-tabs and control characters are displayed.
-
- - Command: goto-line line
- This function moves point to the front of the LINEth line,
- counting from line 1 at beginning of the buffer. If LINE is less
- than 1, it moves point to the beginning of the buffer. If LINE is
- greater than the number of lines in the buffer, it moves point to
- the end of the buffer--that is, the _end of the last line_ of the
- buffer. This is the only case in which `goto-line' does not
- necessarily move to the beginning of a line.
-
- If narrowing is in effect, then LINE still counts from the
- beginning of the buffer, but point cannot go outside the accessible
- portion. So `goto-line' moves point to the beginning or end of the
- accessible portion, if the line number specifies an inaccessible
- position.
-
- The return value of `goto-line' is the difference between LINE and
- the line number of the line to which point actually was able to
- move (in the full buffer, before taking account of narrowing).
- Thus, the value is positive if the scan encounters the real end of
- the buffer. The value is zero if scan encounters the end of the
- accessible portion but not the real end of the buffer.
-
- In an interactive call, LINE is the numeric prefix argument if one
- has been provided. Otherwise LINE is read in the minibuffer.
-
- - Command: beginning-of-line &optional count buffer
- This function moves point to the beginning of the current line.
- With an argument COUNT not `nil' or 1, it moves forward COUNT-1
- lines and then to the beginning of the line. BUFFER defaults to
- the current buffer if omitted.
-
- If this function reaches the end of the buffer (or of the
- accessible portion, if narrowing is in effect), it positions point
- there. No error is signaled.
-
- - Command: end-of-line &optional count buffer
- This function moves point to the end of the current line. With an
- argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
- then to the end of the line. BUFFER defaults to the current
- buffer if omitted.
-
- If this function reaches the end of the buffer (or of the
- accessible portion, if narrowing is in effect), it positions point
- there. No error is signaled.
-
- - Command: forward-line &optional count buffer
- This function moves point forward COUNT lines, to the beginning of
- the line. If COUNT is negative, it moves point -COUNT lines
- backward, to the beginning of a line. If COUNT is zero, it moves
- point to the beginning of the current line. BUFFER defaults to
- the current buffer if omitted.
-
- If `forward-line' encounters the beginning or end of the buffer (or
- of the accessible portion) before finding that many lines, it sets
- point there. No error is signaled.
-
- `forward-line' returns the difference between COUNT and the number
- of lines actually moved. If you attempt to move down five lines
- from the beginning of a buffer that has only three lines, point
- stops at the end of the last line, and the value will be 2.
-
- In an interactive call, COUNT is the numeric prefix argument.
-
- - Function: count-lines start end
- This function returns the number of lines between the positions
- START and END in the current buffer. If START and END are equal,
- then it returns 0. Otherwise it returns at least 1, even if START
- and END are on the same line. This is because the text between
- them, considered in isolation, must contain at least one line
- unless it is empty.
-
- Here is an example of using `count-lines':
-
- (defun current-line ()
- "Return the vertical position of point..."
- (+ (count-lines (window-start) (point))
- (if (= (current-column) 0) 1 0)
- -1))
-
- Also see the functions `bolp' and `eolp' in *Note Near Point::.
-These functions do not move point, but test whether it is already at the
-beginning or end of a line.
-
-\1f
-File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
-
-Motion by Screen Lines
-----------------------
-
- The line functions in the previous section count text lines,
-delimited only by newline characters. By contrast, these functions
-count screen lines, which are defined by the way the text appears on
-the screen. A text line is a single screen line if it is short enough
-to fit the width of the selected window, but otherwise it may occupy
-several screen lines.
-
- In some cases, text lines are truncated on the screen rather than
-continued onto additional screen lines. In these cases,
-`vertical-motion' moves point much like `forward-line'. *Note
-Truncation::.
-
- Because the width of a given string depends on the flags that control
-the appearance of certain characters, `vertical-motion' behaves
-differently, for a given piece of text, depending on the buffer it is
-in, and even on the selected window (because the width, the truncation
-flag, and display table may vary between windows). *Note Usual
-Display::.
-
- These functions scan text to determine where screen lines break, and
-thus take time proportional to the distance scanned. If you intend to
-use them heavily, Emacs provides caches which may improve the
-performance of your code. *Note cache-long-line-scans: Text Lines.
-
- - Function: vertical-motion count &optional window pixels
- This function moves point to the start of the frame line COUNT
- frame lines down from the frame line containing point. If COUNT
- is negative, it moves up instead. The optional second argument
- WINDOW may be used to specify a window other than the selected
- window in which to perform the motion.
-
- Normally, `vertical-motion' returns the number of lines moved. The
- value may be less in absolute value than COUNT if the beginning or
- end of the buffer was reached. If the optional third argument,
- PIXELS is non-`nil', the vertical pixel height of the motion which
- took place is returned instead of the actual number of lines
- moved. A motion of zero lines returns the height of the current
- line.
-
- Note that `vertical-motion' sets WINDOW's buffer's point, not
- WINDOW's point. (This differs from FSF Emacs, which buggily always
- sets current buffer's point, regardless of WINDOW.)
-
- - Function: vertical-motion-pixels count &optional window how
- This function moves point to the start of the frame line PIXELS
- vertical pixels down from the frame line containing point, or up if
- PIXELS is negative. The optional second argument WINDOW is the
- window to move in, and defaults to the selected window. The
- optional third argument HOW specifies the stopping condition. A
- negative integer indicates that the motion should be no more than
- PIXELS. A positive value indicates that the motion should be at
- least PIXELS. Any other value indicates that the motion should be
- as close as possible to PIXELS.
-
- - Command: move-to-window-line count &optional window
- This function moves point with respect to the text currently
- displayed in WINDOW, which defaults to the selected window. It
- moves point to the beginning of the screen line COUNT screen lines
- from the top of the window. If COUNT is negative, that specifies a
- position -COUNT lines from the bottom (or the last line of the
- buffer, if the buffer ends above the specified screen position).
-
- If COUNT is `nil', then point moves to the beginning of the line
- in the middle of the window. If the absolute value of COUNT is
- greater than the size of the window, then point moves to the place
- that would appear on that screen line if the window were tall
- enough. This will probably cause the next redisplay to scroll to
- bring that location onto the screen.
-
- In an interactive call, COUNT is the numeric prefix argument.
-
- The value returned is the window line number point has moved to,
- with the top line in the window numbered 0.
-
-\1f
-File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
-
-Moving over Balanced Expressions
---------------------------------
-
- Here are several functions concerned with balanced-parenthesis
-expressions (also called "sexps" in connection with moving across them
-in XEmacs). The syntax table controls how these functions interpret
-various characters; see *Note Syntax Tables::. *Note Parsing
-Expressions::, for lower-level primitives for scanning sexps or parts of
-sexps. For user-level commands, see *Note Lists and Sexps:
-(emacs)Lists and Sexps.
-
- - Command: forward-list &optional arg
- This function moves forward across ARG balanced groups of
- parentheses. (Other syntactic entities such as words or paired
- string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
- is negative, move backward across that many groups of parentheses.
-
- - Command: backward-list &optional arg
- This function moves backward across ARG balanced groups of
- parentheses. (Other syntactic entities such as words or paired
- string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
- is negative, move forward across that many groups of parentheses.
-
- - Command: up-list arg
- This function moves forward out of ARG levels of parentheses. A
- negative argument means move backward but still to a less deep
- spot.
-
- - Command: down-list arg
- This function moves forward into ARG levels of parentheses. A
- negative argument means move backward but still go deeper in
- parentheses (-ARG levels).
-
- - Command: forward-sexp &optional arg
- This function moves forward across ARG balanced expressions.
- Balanced expressions include both those delimited by parentheses
- and other kinds, such as words and string constants. ARG defaults
- to 1 if omitted. If ARG is negative, move backward across that
- many balanced expressions. For example,
-
- ---------- Buffer: foo ----------
- (concat-!- "foo " (car x) y z)
- ---------- Buffer: foo ----------
-
- (forward-sexp 3)
- => nil
-
- ---------- Buffer: foo ----------
- (concat "foo " (car x) y-!- z)
- ---------- Buffer: foo ----------
-
- - Command: backward-sexp &optional arg
- This function moves backward across ARG balanced expressions. ARG
- defaults to 1 if omitted. If ARG is negative, move forward across
- that many balanced expressions.
-
- - Command: beginning-of-defun &optional arg
- This function moves back to the ARGth beginning of a defun. If
- ARG is negative, this actually moves forward, but it still moves
- to the beginning of a defun, not to the end of one. ARG defaults
- to 1 if omitted.
-
- - Command: end-of-defun &optional arg
- This function moves forward to the ARGth end of a defun. If ARG
- is negative, this actually moves backward, but it still moves to
- the end of a defun, not to the beginning of one. ARG defaults to
- 1 if omitted.
-
- - User Option: defun-prompt-regexp
- If non-`nil', this variable holds a regular expression that
- specifies what text can appear before the open-parenthesis that
- starts a defun. That is to say, a defun begins on a line that
- starts with a match for this regular expression, followed by a
- character with open-parenthesis syntax.
-
-\1f
-File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
-
-Skipping Characters
--------------------
-
- The following two functions move point over a specified set of
-characters. For example, they are often used to skip whitespace. For
-related functions, see *Note Motion and Syntax::.
-
- - Function: skip-chars-forward character-set &optional limit buffer
- This function moves point in BUFFER forward, skipping over a given
- set of characters. It examines the character following point,
- then advances point if the character matches CHARACTER-SET. This
- continues until it reaches a character that does not match. The
- function returns `nil'. BUFFER defaults to the current buffer if
- omitted.
-
- The argument CHARACTER-SET is like the inside of a `[...]' in a
- regular expression except that `]' is never special and `\' quotes
- `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
- stopping before the first non-letter, and `"^a-zA-Z'" skips
- non-letters stopping before the first letter. *Note Regular
- Expressions::.
-
- If LIMIT is supplied (it must be a number or a marker), it
- specifies the maximum position in the buffer that point can be
- skipped to. Point will stop at or before LIMIT.
-
- In the following example, point is initially located directly
- before the `T'. After the form is evaluated, point is located at
- the end of that line (between the `t' of `hat' and the newline).
- The function skips all letters and spaces, but not newlines.
-
- ---------- Buffer: foo ----------
- I read "-!-The cat in the hat
- comes back" twice.
- ---------- Buffer: foo ----------
-
- (skip-chars-forward "a-zA-Z ")
- => nil
-
- ---------- Buffer: foo ----------
- I read "The cat in the hat-!-
- comes back" twice.
- ---------- Buffer: foo ----------
-
- - Function: skip-chars-backward character-set &optional limit buffer
- This function moves point backward, skipping characters that match
- CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
- except for the direction of motion.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices
+
+The Selected Console and Device
+===============================
+
+ - Function: select-console console
+ This function selects the console CONSOLE. Subsequent editing
+ commands apply to its selected device, selected frame, and selected
+ window. The selection of CONSOLE lasts until the next time the
+ user does something to select a different console, or until the
+ next time this function is called.
+
+ - Function: selected-console
+ This function returns the console which is currently active.
+
+ - Function: select-device device
+ This function selects the device DEVICE.
+
+ - Function: selected-device &optional console
+ This function returns the device which is currently active. If
+ optional CONSOLE is non-`nil', this function returns the device
+ that would be currently active if CONSOLE were the selected
+ console.
+
+\1f
+File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
+
+Console and Device I/O
+======================
+
+ - Function: console-disable-input console
+ This function disables input on console CONSOLE.
+
+ - Function: console-enable-input console
+ This function enables input on console CONSOLE.
+
+ Each device has a "baud rate" value associated with it. On most
+systems, changing this value will affect the amount of padding and
+other strategic decisions made during redisplay.
+
+ - Function: device-baud-rate &optional device
+ This function returns the output baud rate of DEVICE.
+
+ - Function: set-device-baud-rate device rate
+ This function sets the output baud rate of DEVICE to RATE.
+
+\1f
+File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
+
+Positions
+*********
+
+ A "position" is the index of a character in the text of a buffer.
+More precisely, a position identifies the place between two characters
+(or before the first character, or after the last character), so we can
+speak of the character before or after a given position. However, we
+often speak of the character "at" a position, meaning the character
+after that position.
+
+ Positions are usually represented as integers starting from 1, but
+can also be represented as "markers"--special objects that relocate
+automatically when text is inserted or deleted so they stay with the
+surrounding characters. *Note Markers::.
+
+* Menu:
+
+* Point:: The special position where editing takes place.
+* Motion:: Changing point.
+* Excursions:: Temporary motion and buffer changes.
+* Narrowing:: Restricting editing to a portion of the buffer.
+
+\1f
+File: lispref.info, Node: Point, Next: Motion, Up: Positions
+
+Point
+=====
+
+ "Point" is a special buffer position used by many editing commands,
+including the self-inserting typed characters and text insertion
+functions. Other commands move point through the text to allow editing
+and insertion at different places.
+
+ Like other positions, point designates a place between two characters
+(or before the first character, or after the last character), rather
+than a particular character. Usually terminals display the cursor over
+the character that immediately follows point; point is actually before
+the character on which the cursor sits.
+
+ The value of point is a number between 1 and the buffer size plus 1.
+If narrowing is in effect (*note Narrowing::), then point is constrained
+to fall within the accessible portion of the buffer (possibly at one end
+of it).
+
+ Each buffer has its own value of point, which is independent of the
+value of point in other buffers. Each window also has a value of point,
+which is independent of the value of point in other windows on the same
+buffer. This is why point can have different values in various windows
+that display the same buffer. When a buffer appears in only one window,
+the buffer's point and the window's point normally have the same value,
+so the distinction is rarely important. *Note Window Point::, for more
+details.
+
+ - Function: point &optional buffer
+ This function returns the value of point in BUFFER, as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ (point)
+ => 175
+
+ - Function: point-min &optional buffer
+ This function returns the minimum accessible value of point in
+ BUFFER. This is normally 1, but if narrowing is in effect, it is
+ the position of the start of the region that you narrowed to.
+ (*Note Narrowing::.) BUFFER defaults to the current buffer if
+ omitted.
+
+ - Function: point-max &optional buffer
+ This function returns the maximum accessible value of point in
+ BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
+ in effect, in which case it is the position of the end of the
+ region that you narrowed to. (*note Narrowing::). BUFFER defaults
+ to the current buffer if omitted.
+
+ - Function: buffer-end flag &optional buffer
+ This function returns `(point-min buffer)' if FLAG is less than 1,
+ `(point-max buffer)' otherwise. The argument FLAG must be a
+ number. BUFFER defaults to the current buffer if omitted.
+
+ - Function: buffer-size &optional buffer
+ This function returns the total number of characters in BUFFER.
+ In the absence of any narrowing (*note Narrowing::), `point-max'
+ returns a value one larger than this. BUFFER defaults to the
+ current buffer if omitted.
+
+ (buffer-size)
+ => 35
+ (point-max)
+ => 36
+
+ - Variable: buffer-saved-size
+ The value of this buffer-local variable is the former length of the
+ current buffer, as of the last time it was read in, saved or
+ auto-saved.
+
+\1f
+File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
+
+Motion
+======
+
+ Motion functions change the value of point, either relative to the
+current value of point, relative to the beginning or end of the buffer,
+or relative to the edges of the selected window. *Note Point::.
+
+* Menu:
+
+* Character Motion:: Moving in terms of characters.
+* Word Motion:: Moving in terms of words.
+* Buffer End Motion:: Moving to the beginning or end of the buffer.
+* Text Lines:: Moving in terms of lines of text.
+* Screen Lines:: Moving in terms of lines as displayed.
+* List Motion:: Moving by parsing lists and sexps.
+* Skipping Characters:: Skipping characters belonging to a certain set.
+
+\1f
+File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
+
+Motion by Characters
+--------------------
+
+ These functions move point based on a count of characters.
+`goto-char' is the fundamental primitive; the other functions use that.
+
+ - Command: goto-char position &optional buffer
+ This function sets point in `buffer' to the value POSITION. If
+ POSITION is less than 1, it moves point to the beginning of the
+ buffer. If POSITION is greater than the length of the buffer, it
+ moves point to the end. BUFFER defaults to the current buffer if
+ omitted.
+
+ If narrowing is in effect, POSITION still counts from the
+ beginning of the buffer, but point cannot go outside the accessible
+ portion. If POSITION is out of range, `goto-char' moves point to
+ the beginning or the end of the accessible portion.
+
+ When this function is called interactively, POSITION is the
+ numeric prefix argument, if provided; otherwise it is read from the
+ minibuffer.
+
+ `goto-char' returns POSITION.
+
+ - Command: forward-char &optional count buffer
+ This function moves point COUNT characters forward, towards the
+ end of the buffer (or backward, towards the beginning of the
+ buffer, if COUNT is negative). If the function attempts to move
+ point past the beginning or end of the buffer (or the limits of
+ the accessible portion, when narrowing is in effect), an error is
+ signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+ BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ - Command: backward-char &optional count buffer
+ This function moves point COUNT characters backward, towards the
+ beginning of the buffer (or forward, towards the end of the
+ buffer, if COUNT is negative). If the function attempts to move
+ point past the beginning or end of the buffer (or the limits of
+ the accessible portion, when narrowing is in effect), an error is
+ signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+ BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+\1f
+File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
+
+Motion by Words
+---------------
+
+ These functions for parsing words use the syntax table to decide
+whether a given character is part of a word. *Note Syntax Tables::.
+
+ - Command: forward-word count &optional buffer
+ This function moves point forward COUNT words (or backward if
+ COUNT is negative). Normally it returns `t'. If this motion
+ encounters the beginning or end of the buffer, or the limits of the
+ accessible portion when narrowing is in effect, point stops there
+ and the value is `nil'. BUFFER defaults to the current buffer if
+ omitted.
+
+ In an interactive call, COUNT is set to the numeric prefix
+ argument.
+
+ - Command: backward-word count &optional buffer
+ This function is just like `forward-word', except that it moves
+ backward until encountering the front of a word, rather than
+ forward. BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is set to the numeric prefix
+ argument.
+
+ This function is rarely used in programs, as it is more efficient
+ to call `forward-word' with a negative argument.
+
+ - Variable: words-include-escapes
+ This variable affects the behavior of `forward-word' and everything
+ that uses it. If it is non-`nil', then characters in the "escape"
+ and "character quote" syntax classes count as part of words.
+ Otherwise, they do not.
+
+\1f
+File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
+
+Motion to an End of the Buffer
+------------------------------
+
+ To move point to the beginning of the buffer, write:
+
+ (goto-char (point-min))
+
+Likewise, to move to the end of the buffer, use:
+
+ (goto-char (point-max))
+
+ Here are two commands that users use to do these things. They are
+documented here to warn you not to use them in Lisp programs, because
+they set the mark and display messages in the echo area.
+
+ - Command: beginning-of-buffer &optional n
+ This function moves point to the beginning of the buffer (or the
+ limits of the accessible portion, when narrowing is in effect),
+ setting the mark at the previous position. If N is non-`nil',
+ then it puts point N tenths of the way from the beginning of the
+ buffer.
+
+ In an interactive call, N is the numeric prefix argument, if
+ provided; otherwise N defaults to `nil'.
+
+ Don't use this function in Lisp programs!
+
+ - Command: end-of-buffer &optional n
+ This function moves point to the end of the buffer (or the limits
+ of the accessible portion, when narrowing is in effect), setting
+ the mark at the previous position. If N is non-`nil', then it puts
+ point N tenths of the way from the end of the buffer.
+
+ In an interactive call, N is the numeric prefix argument, if
+ provided; otherwise N defaults to `nil'.
+
+ Don't use this function in Lisp programs!
+
+\1f
+File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
+
+Motion by Text Lines
+--------------------
+
+ Text lines are portions of the buffer delimited by newline
+characters, which are regarded as part of the previous line. The first
+text line begins at the beginning of the buffer, and the last text line
+ends at the end of the buffer whether or not the last character is a
+newline. The division of the buffer into text lines is not affected by
+the width of the window, by line continuation in display, or by how
+tabs and control characters are displayed.
+
+ - Command: goto-line line
+ This function moves point to the front of the LINEth line,
+ counting from line 1 at beginning of the buffer. If LINE is less
+ than 1, it moves point to the beginning of the buffer. If LINE is
+ greater than the number of lines in the buffer, it moves point to
+ the end of the buffer--that is, the _end of the last line_ of the
+ buffer. This is the only case in which `goto-line' does not
+ necessarily move to the beginning of a line.
+
+ If narrowing is in effect, then LINE still counts from the
+ beginning of the buffer, but point cannot go outside the accessible
+ portion. So `goto-line' moves point to the beginning or end of the
+ accessible portion, if the line number specifies an inaccessible
+ position.
+
+ The return value of `goto-line' is the difference between LINE and
+ the line number of the line to which point actually was able to
+ move (in the full buffer, before taking account of narrowing).
+ Thus, the value is positive if the scan encounters the real end of
+ the buffer. The value is zero if scan encounters the end of the
+ accessible portion but not the real end of the buffer.
+
+ In an interactive call, LINE is the numeric prefix argument if one
+ has been provided. Otherwise LINE is read in the minibuffer.
+
+ - Command: beginning-of-line &optional count buffer
+ This function moves point to the beginning of the current line.
+ With an argument COUNT not `nil' or 1, it moves forward COUNT-1
+ lines and then to the beginning of the line. BUFFER defaults to
+ the current buffer if omitted.
+
+ If this function reaches the end of the buffer (or of the
+ accessible portion, if narrowing is in effect), it positions point
+ there. No error is signaled.
+
+ - Command: end-of-line &optional count buffer
+ This function moves point to the end of the current line. With an
+ argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
+ then to the end of the line. BUFFER defaults to the current
+ buffer if omitted.
+
+ If this function reaches the end of the buffer (or of the
+ accessible portion, if narrowing is in effect), it positions point
+ there. No error is signaled.
+
+ - Command: forward-line &optional count buffer
+ This function moves point forward COUNT lines, to the beginning of
+ the line. If COUNT is negative, it moves point -COUNT lines
+ backward, to the beginning of a line. If COUNT is zero, it moves
+ point to the beginning of the current line. BUFFER defaults to
+ the current buffer if omitted.
+
+ If `forward-line' encounters the beginning or end of the buffer (or
+ of the accessible portion) before finding that many lines, it sets
+ point there. No error is signaled.
+
+ `forward-line' returns the difference between COUNT and the number
+ of lines actually moved. If you attempt to move down five lines
+ from the beginning of a buffer that has only three lines, point
+ stops at the end of the last line, and the value will be 2.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ - Function: count-lines start end
+ This function returns the number of lines between the positions
+ START and END in the current buffer. If START and END are equal,
+ then it returns 0. Otherwise it returns at least 1, even if START
+ and END are on the same line. This is because the text between
+ them, considered in isolation, must contain at least one line
+ unless it is empty.
+
+ Here is an example of using `count-lines':
+
+ (defun current-line ()
+ "Return the vertical position of point..."
+ (+ (count-lines (window-start) (point))
+ (if (= (current-column) 0) 1 0)
+ -1))
+
+ Also see the functions `bolp' and `eolp' in *Note Near Point::.
+These functions do not move point, but test whether it is already at the
+beginning or end of a line.
+
+\1f
+File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
+
+Motion by Screen Lines
+----------------------
+
+ The line functions in the previous section count text lines,
+delimited only by newline characters. By contrast, these functions
+count screen lines, which are defined by the way the text appears on
+the screen. A text line is a single screen line if it is short enough
+to fit the width of the selected window, but otherwise it may occupy
+several screen lines.
+
+ In some cases, text lines are truncated on the screen rather than
+continued onto additional screen lines. In these cases,
+`vertical-motion' moves point much like `forward-line'. *Note
+Truncation::.
+
+ Because the width of a given string depends on the flags that control
+the appearance of certain characters, `vertical-motion' behaves
+differently, for a given piece of text, depending on the buffer it is
+in, and even on the selected window (because the width, the truncation
+flag, and display table may vary between windows). *Note Usual
+Display::.
+
+ These functions scan text to determine where screen lines break, and
+thus take time proportional to the distance scanned. If you intend to
+use them heavily, Emacs provides caches which may improve the
+performance of your code. *Note cache-long-line-scans: Text Lines.
+
+ - Function: vertical-motion count &optional window pixels
+ This function moves point to the start of the frame line COUNT
+ frame lines down from the frame line containing point. If COUNT
+ is negative, it moves up instead. The optional second argument
+ WINDOW may be used to specify a window other than the selected
+ window in which to perform the motion.
+
+ Normally, `vertical-motion' returns the number of lines moved. The
+ value may be less in absolute value than COUNT if the beginning or
+ end of the buffer was reached. If the optional third argument,
+ PIXELS is non-`nil', the vertical pixel height of the motion which
+ took place is returned instead of the actual number of lines
+ moved. A motion of zero lines returns the height of the current
+ line.
+
+ Note that `vertical-motion' sets WINDOW's buffer's point, not
+ WINDOW's point. (This differs from FSF Emacs, which buggily always
+ sets current buffer's point, regardless of WINDOW.)
+
+ - Function: vertical-motion-pixels count &optional window how
+ This function moves point to the start of the frame line PIXELS
+ vertical pixels down from the frame line containing point, or up if
+ PIXELS is negative. The optional second argument WINDOW is the
+ window to move in, and defaults to the selected window. The
+ optional third argument HOW specifies the stopping condition. A
+ negative integer indicates that the motion should be no more than
+ PIXELS. A positive value indicates that the motion should be at
+ least PIXELS. Any other value indicates that the motion should be
+ as close as possible to PIXELS.
+
+ - Command: move-to-window-line count &optional window
+ This function moves point with respect to the text currently
+ displayed in WINDOW, which defaults to the selected window. It
+ moves point to the beginning of the screen line COUNT screen lines
+ from the top of the window. If COUNT is negative, that specifies a
+ position -COUNT lines from the bottom (or the last line of the
+ buffer, if the buffer ends above the specified screen position).
+
+ If COUNT is `nil', then point moves to the beginning of the line
+ in the middle of the window. If the absolute value of COUNT is
+ greater than the size of the window, then point moves to the place
+ that would appear on that screen line if the window were tall
+ enough. This will probably cause the next redisplay to scroll to
+ bring that location onto the screen.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ The value returned is the window line number point has moved to,
+ with the top line in the window numbered 0.
+
+\1f
+File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
+
+Moving over Balanced Expressions
+--------------------------------
+
+ Here are several functions concerned with balanced-parenthesis
+expressions (also called "sexps" in connection with moving across them
+in XEmacs). The syntax table controls how these functions interpret
+various characters; see *Note Syntax Tables::. *Note Parsing
+Expressions::, for lower-level primitives for scanning sexps or parts of
+sexps. For user-level commands, see *Note Lists and Sexps:
+(emacs)Lists and Sexps.
+
+ - Command: forward-list &optional arg
+ This function moves forward across ARG balanced groups of
+ parentheses. (Other syntactic entities such as words or paired
+ string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
+ is negative, move backward across that many groups of parentheses.
+
+ - Command: backward-list &optional arg
+ This function moves backward across ARG balanced groups of
+ parentheses. (Other syntactic entities such as words or paired
+ string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
+ is negative, move forward across that many groups of parentheses.
+
+ - Command: up-list arg
+ This function moves forward out of ARG levels of parentheses. A
+ negative argument means move backward but still to a less deep
+ spot.
+
+ - Command: down-list arg
+ This function moves forward into ARG levels of parentheses. A
+ negative argument means move backward but still go deeper in
+ parentheses (-ARG levels).
+
+ - Command: forward-sexp &optional arg
+ This function moves forward across ARG balanced expressions.
+ Balanced expressions include both those delimited by parentheses
+ and other kinds, such as words and string constants. ARG defaults
+ to 1 if omitted. If ARG is negative, move backward across that
+ many balanced expressions. For example,
+
+ ---------- Buffer: foo ----------
+ (concat-!- "foo " (car x) y z)
+ ---------- Buffer: foo ----------
+
+ (forward-sexp 3)
+ => nil
+
+ ---------- Buffer: foo ----------
+ (concat "foo " (car x) y-!- z)
+ ---------- Buffer: foo ----------
+
+ - Command: backward-sexp &optional arg
+ This function moves backward across ARG balanced expressions. ARG
+ defaults to 1 if omitted. If ARG is negative, move forward across
+ that many balanced expressions.
+
+ - Command: beginning-of-defun &optional arg
+ This function moves back to the ARGth beginning of a defun. If
+ ARG is negative, this actually moves forward, but it still moves
+ to the beginning of a defun, not to the end of one. ARG defaults
+ to 1 if omitted.
+
+ - Command: end-of-defun &optional arg
+ This function moves forward to the ARGth end of a defun. If ARG
+ is negative, this actually moves backward, but it still moves to
+ the end of a defun, not to the beginning of one. ARG defaults to
+ 1 if omitted.
+
+ - User Option: defun-prompt-regexp
+ If non-`nil', this variable holds a regular expression that
+ specifies what text can appear before the open-parenthesis that
+ starts a defun. That is to say, a defun begins on a line that
+ starts with a match for this regular expression, followed by a
+ character with open-parenthesis syntax.
+
+\1f
+File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
+
+Skipping Characters
+-------------------
+
+ The following two functions move point over a specified set of
+characters. For example, they are often used to skip whitespace. For
+related functions, see *Note Motion and Syntax::.
+
+ - Function: skip-chars-forward character-set &optional limit buffer
+ This function moves point in BUFFER forward, skipping over a given
+ set of characters. It examines the character following point,
+ then advances point if the character matches CHARACTER-SET. This
+ continues until it reaches a character that does not match. The
+ function returns `nil'. BUFFER defaults to the current buffer if
+ omitted.
+
+ The argument CHARACTER-SET is like the inside of a `[...]' in a
+ regular expression except that `]' is never special and `\' quotes
+ `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
+ stopping before the first non-letter, and `"^a-zA-Z'" skips
+ non-letters stopping before the first letter. *Note Regular
+ Expressions::.
+
+ If LIMIT is supplied (it must be a number or a marker), it
+ specifies the maximum position in the buffer that point can be
+ skipped to. Point will stop at or before LIMIT.
+
+ In the following example, point is initially located directly
+ before the `T'. After the form is evaluated, point is located at
+ the end of that line (between the `t' of `hat' and the newline).
+ The function skips all letters and spaces, but not newlines.
+
+ ---------- Buffer: foo ----------
+ I read "-!-The cat in the hat
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ (skip-chars-forward "a-zA-Z ")
+ => nil
+
+ ---------- Buffer: foo ----------
+ I read "The cat in the hat-!-
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ - Function: skip-chars-backward character-set &optional limit buffer
+ This function moves point backward, skipping characters that match
+ CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
+ except for the direction of motion.
+
+\1f
File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
Excursions
- Function: move-marker marker position &optional buffer
This is another name for `set-marker'.
-\1f
-File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
-
-The Mark
-========
-
- One special marker in each buffer is designated "the mark". It
-records a position for the user for the sake of commands such as `C-w'
-and `C-x <TAB>'. Lisp programs should set the mark only to values that
-have a potential use to the user, and never for their own internal
-purposes. For example, the `replace-regexp' command sets the mark to
-the value of point before doing any replacements, because this enables
-the user to move back there conveniently after the replace is finished.
-
- Once the mark "exists" in a buffer, it normally never ceases to
-exist. However, it may become "inactive", and usually does so after
-each command (other than simple motion commands and some commands that
-explicitly activate the mark). When the mark is active, the region
-between point and the mark is called the "active region" and is
-highlighted specially.
-
- Many commands are designed so that when called interactively they
-operate on the text between point and the mark. Such commands work
-only when an active region exists, i.e. when the mark is active. (The
-reason for this is to prevent you from accidentally deleting or
-changing large chunks of your text.) If you are writing such a command,
-don't examine the mark directly; instead, use `interactive' with the
-`r' specification. This provides the values of point and the mark as
-arguments to the command in an interactive call, but permits other Lisp
-programs to specify arguments explicitly, and automatically signals an
-error if the command is called interactively when no active region
-exists. *Note Interactive Codes::.
-
- Each buffer has its own value of the mark that is independent of the
-value of the mark in other buffers. (When a buffer is created, the mark
-exists but does not point anywhere. We consider this state as "the
-absence of a mark in that buffer.") However, only one active region can
-exist at a time. Activating the mark in one buffer automatically
-deactivates an active mark in any other buffer. Note that the user can
-explicitly activate a mark at any time by using the command
-`activate-region' (normally bound to `M-C-z') or by using the command
-`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
-side effect of activating the mark.
-
- Some people do not like active regions, so they disable this behavior
-by setting the variable `zmacs-regions' to `nil'. This makes the mark
-always active (except when a buffer is just created and the mark points
-nowhere), and turns off the highlighting of the region between point
-and the mark. Commands that explicitly retrieve the value of the mark
-should make sure that they behave correctly and consistently
-irrespective of the setting of `zmacs-regions'; some primitives are
-provided to ensure this behavior.
-
- In addition to the mark, each buffer has a "mark ring" which is a
-list of markers containing previous values of the mark. When editing
-commands change the mark, they should normally save the old value of the
-mark on the mark ring. The variable `mark-ring-max' specifies the
-maximum number of entries in the mark ring; once the list becomes this
-long, adding a new element deletes the last element.
-
- - Function: mark &optional force buffer
- This function returns BUFFER's mark position as an integer.
- BUFFER defaults to the current buffer if omitted.
-
- If the mark is inactive, `mark' normally returns `nil'. However,
- if FORCE is non-`nil', then `mark' returns the mark position
- anyway--or `nil', if the mark is not yet set for the buffer.
-
- (Remember that if ZMACS-REGIONS is `nil', the mark is always
- active as long as it exists, and the FORCE argument will have no
- effect.)
-
- If you are using this in an editing command, you are most likely
- making a mistake; see the documentation of `set-mark' below.
-
- - Function: mark-marker inactive-p buffer
- This function returns BUFFER's mark. BUFFER defaults to the
- current buffer if omitted. This is the very marker that records
- the mark location inside XEmacs, not a copy. Therefore, changing
- this marker's position will directly affect the position of the
- mark. Don't do it unless that is the effect you want.
-
- If the mark is inactive, `mark-marker' normally returns `nil'.
- However, if FORCE is non-`nil', then `mark-marker' returns the
- mark anyway.
- (setq m (mark-marker))
- => #<marker at 3420 in markers.texi>
- (set-marker m 100)
- => #<marker at 100 in markers.texi>
- (mark-marker)
- => #<marker at 100 in markers.texi>
-
- Like any marker, this marker can be set to point at any buffer you
- like. We don't recommend that you make it point at any buffer
- other than the one of which it is the mark. If you do, it will
- yield perfectly consistent, but rather odd, results.
-
- - Function: set-mark position &optional buffer
- This function sets `buffer''s mark to POSITION, and activates the
- mark. BUFFER defaults to the current buffer if omitted. The old
- value of the mark is _not_ pushed onto the mark ring.
-
- *Please note:* Use this function only if you want the user to see
- that the mark has moved, and you want the previous mark position to
- be lost. Normally, when a new mark is set, the old one should go
- on the `mark-ring'. For this reason, most applications should use
- `push-mark' and `pop-mark', not `set-mark'.
-
- Novice XEmacs Lisp programmers often try to use the mark for the
- wrong purposes. The mark saves a location for the user's
- convenience. An editing command should not alter the mark unless
- altering the mark is part of the user-level functionality of the
- command. (And, in that case, this effect should be documented.)
- To remember a location for internal use in the Lisp program, store
- it in a Lisp variable. For example:
-
- (let ((beg (point)))
- (forward-line 1)
- (delete-region beg (point))).
-
- - Command: exchange-point-and-mark &optional dont-activate-region
- This function exchanges the positions of point and the mark. It
- is intended for interactive use. The mark is also activated
- unless DONT-ACTIVATE-REGION is non-`nil'.
-
- - Function: push-mark &optional position nomsg activate buffer
- This function sets BUFFER's mark to POSITION, and pushes a copy of
- the previous mark onto `mark-ring'. BUFFER defaults to the
- current buffer if omitted. If POSITION is `nil', then the value
- of point is used. `push-mark' returns `nil'.
-
- If the last global mark pushed was not in BUFFER, also push
- POSITION on the global mark ring (see below).
-
- The function `push-mark' normally _does not_ activate the mark.
- To do that, specify `t' for the argument ACTIVATE.
-
- A `Mark set' message is displayed unless NOMSG is non-`nil'.
-
- - Function: pop-mark
- This function pops off the top element of `mark-ring' and makes
- that mark become the buffer's actual mark. This does not move
- point in the buffer, and it does nothing if `mark-ring' is empty.
- It deactivates the mark.
-
- The return value is not meaningful.
-
- - Variable: mark-ring
- The value of this buffer-local variable is the list of saved former
- marks of the current buffer, most recent first.
-
- mark-ring
- => (#<marker at 11050 in markers.texi>
- #<marker at 10832 in markers.texi>
- ...)
-
- - User Option: mark-ring-max
- The value of this variable is the maximum size of `mark-ring'. If
- more marks than this are pushed onto the `mark-ring', `push-mark'
- discards an old mark when it adds a new one.
-
- In additional to a per-buffer mark ring, there is a "global mark
-ring". Marks are pushed onto the global mark ring the first time you
-set a mark after switching buffers.
-
- - Variable: global-mark-ring
- The value of this variable is the list of saved former global
- marks, most recent first.
-
- - User Option: mark-ring-max
- The value of this variable is the maximum size of
- `global-mark-ring'. If more marks than this are pushed onto the
- `global-mark-ring', `push-mark' discards an old mark when it adds
- a new one.
-
- - Command: pop-global-mark
- This function pops a mark off the global mark ring and jumps to
- that location.
-
-\1f
-File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
-
-The Region
-==========
-
- The text between point and the mark is known as "the region".
-Various functions operate on text delimited by point and the mark, but
-only those functions specifically related to the region itself are
-described here.
-
- When `zmacs-regions' is non-`nil' (this is the default), the concept
-of an "active region" exists. The region is active when the
-corresponding mark is active. Note that only one active region at a
-time can exist--i.e. only one buffer's region is active at a time.
-*Note The Mark::, for more information about active regions.
-
- - User Option: zmacs-regions
- If non-`nil' (the default), active regions are used. *Note The
- Mark::, for a detailed explanation of what this means.
-
- A number of functions are provided for explicitly determining the
-bounds of the region and whether it is active. Few programs need to use
-these functions, however. A command designed to operate on a region
-should normally use `interactive' with the `r' specification to find
-the beginning and end of the region. This lets other Lisp programs
-specify the bounds explicitly as arguments and automatically respects
-the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
-
- - Function: region-beginning &optional buffer
- This function returns the position of the beginning of BUFFER's
- region (as an integer). This is the position of either point or
- the mark, whichever is smaller. BUFFER defaults to the current
- buffer if omitted.
-
- If the mark does not point anywhere, an error is signaled. Note
- that this function ignores whether the region is active.
-
- - Function: region-end &optional buffer
- This function returns the position of the end of BUFFER's region
- (as an integer). This is the position of either point or the mark,
- whichever is larger. BUFFER defaults to the current buffer if
- omitted.
-
- If the mark does not point anywhere, an error is signaled. Note
- that this function ignores whether the region is active.
-
- - Function: region-exists-p
- This function is non-`nil' if the region exists. If active regions
- are in use (i.e. `zmacs-regions' is true), this means that the
- region is active. Otherwise, this means that the user has pushed
- a mark in this buffer at some point in the past. If this function
- returns `nil', a function that uses the `r' interactive
- specification will cause an error when called interactively.
-
- - Function: region-active-p
- If `zmacs-regions' is true, this is equivalent to
- `region-exists-p'. Otherwise, this function always returns false.
- This function is used by commands such as
- `fill-paragraph-or-region' and `capitalize-region-or-word', which
- operate either on the active region or on something else (e.g. the
- word or paragraph at point).
-
- - Variable: zmacs-region-stays
- If a command sets this variable to true, the currently active
- region will remain activated when the command finishes. (Normally
- the region is deactivated when each command terminates.) If
- ZMACS-REGIONS is false, however, this has no effect. Under normal
- circumstances, you do not need to set this; use the interactive
- specification `_' instead, if you want the region to remain active.
-
- - Function: zmacs-activate-region
- This function activates the region in the current buffer (this is
- equivalent to activating the current buffer's mark). This will
- normally also highlight the text in the active region and set
- ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
- this function has no effect.)
-
- - Function: zmacs-deactivate-region
- This function deactivates the region in the current buffer (this is
- equivalent to deactivating the current buffer's mark). This will
- normally also unhighlight the text in the active region and set
- ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
- this function has no effect.)
-
- - Function: zmacs-update-region
- This function updates the active region, if it's currently active.
- (If there is no active region, this function does nothing.) This
- has the effect of updating the highlighting on the text in the
- region; but you should never need to call this except under rather
- strange circumstances. The command loop automatically calls it
- when appropriate. Calling this function will call the hook
- `zmacs-update-region-hook', if the region is active.
-
- - Variable: zmacs-activate-region-hook
- This normal hook is called when a region becomes active. (Usually
- this happens as a result of a command that activates the region,
- such as `set-mark-command', `activate-region', or
- `exchange-point-and-mark'.) Note that calling
- `zmacs-activate-region' will call this hook, even if the region is
- already active. If ZMACS-REGIONS is false, however, this hook
- will never get called under any circumstances.
-
- - Variable: zmacs-deactivate-region-hook
- This normal hook is called when an active region becomes inactive.
- (Calling `zmacs-deactivate-region' when the region is inactive will
- _not_ cause this hook to be called.) If ZMACS-REGIONS is false,
- this hook will never get called.
-
- - Variable: zmacs-update-region-hook
- This normal hook is called when an active region is "updated" by
- `zmacs-update-region'. This normally gets called at the end of
- each command that sets ZMACS-REGION-STAYS to `t', indicating that
- the region should remain activated. The motion commands do this.
-
-\1f
-File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
-
-Text
-****
-
- This chapter describes the functions that deal with the text in a
-buffer. Most examine, insert, or delete text in the current buffer,
-often in the vicinity of point. Many are interactive. All the
-functions that change the text provide for undoing the changes (*note
-Undo::).
-
- Many text-related functions operate on a region of text defined by
-two buffer positions passed in arguments named START and END. These
-arguments should be either markers (*note Markers::) or numeric
-character positions (*note Positions::). The order of these arguments
-does not matter; it is all right for START to be the end of the region
-and END the beginning. For example, `(delete-region 1 10)' and
-`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
-signaled if either START or END is outside the accessible portion of
-the buffer. In an interactive call, point and the mark are used for
-these arguments.
-
- Throughout this chapter, "text" refers to the characters in the
-buffer, together with their properties (when relevant).
-
-* Menu:
-
-* Near Point:: Examining text in the vicinity of point.
-* Buffer Contents:: Examining text in a general fashion.
-* Comparing Text:: Comparing substrings of buffers.
-* Insertion:: Adding new text to a buffer.
-* Commands for Insertion:: User-level commands to insert text.
-* Deletion:: Removing text from a buffer.
-* User-Level Deletion:: User-level commands to delete text.
-* The Kill Ring:: Where removed text sometimes is saved for later use.
-* Undo:: Undoing changes to the text of a buffer.
-* Maintaining Undo:: How to enable and disable undo information.
- How to control how much information is kept.
-* Filling:: Functions for explicit filling.
-* Margins:: How to specify margins for filling commands.
-* Auto Filling:: How auto-fill mode is implemented to break lines.
-* Sorting:: Functions for sorting parts of the buffer.
-* Columns:: Computing horizontal positions, and using them.
-* Indentation:: Functions to insert or adjust indentation.
-* Case Changes:: Case conversion of parts of the buffer.
-* Text Properties:: Assigning Lisp property lists to text characters.
-* Substitution:: Replacing a given character wherever it appears.
-* Registers:: How registers are implemented. Accessing the text or
- position stored in a register.
-* Transposition:: Swapping two portions of a buffer.
-* Change Hooks:: Supplying functions to be run when text is changed.
-* Transformations:: MD5 and base64 support.
-
-\1f
-File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
-
-Examining Text Near Point
-=========================
-
- Many functions are provided to look at the characters around point.
-Several simple functions are described here. See also `looking-at' in
-*Note Regexp Search::.
-
- Many of these functions take an optional BUFFER argument. In all
-such cases, the current buffer will be used if this argument is
-omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
-usually did not have these optional BUFFER arguments and always
-operated on the current buffer.)
-
- - Function: char-after &optional position buffer
- This function returns the character in the buffer at (i.e.,
- immediately after) position POSITION. If POSITION is out of range
- for this purpose, either before the beginning of the buffer, or at
- or beyond the end, then the value is `nil'. The default for
- POSITION is point. If optional argument BUFFER is `nil', the
- current buffer is assumed.
-
- In the following example, assume that the first character in the
- buffer is `@':
-
- (char-to-string (char-after 1))
- => "@"
-
- - Function: char-before &optional position buffer
- This function returns the character in the current buffer
- immediately before position POSITION. If POSITION is out of range
- for this purpose, either at or before the beginning of the buffer,
- or beyond the end, then the value is `nil'. The default for
- POSITION is point. If optional argument BUFFER is `nil', the
- current buffer is assumed.
-
- - Function: following-char &optional buffer
- This function returns the character following point in the buffer.
- This is similar to `(char-after (point))'. However, if point is at
- the end of the buffer, then the result of `following-char' is 0.
- If optional argument BUFFER is `nil', the current buffer is
- assumed.
-
- Remember that point is always between characters, and the terminal
- cursor normally appears over the character following point.
- Therefore, the character returned by `following-char' is the
- character the cursor is over.
-
- In this example, point is between the `a' and the `c'.
-
- ---------- Buffer: foo ----------
- Gentlemen may cry ``Pea-!-ce! Peace!,''
- but there is no peace.
- ---------- Buffer: foo ----------
-
- (char-to-string (preceding-char))
- => "a"
- (char-to-string (following-char))
- => "c"
-
- - Function: preceding-char &optional buffer
- This function returns the character preceding point in the buffer.
- See above, under `following-char', for an example. If point is at
- the beginning of the buffer, `preceding-char' returns 0. If
- optional argument BUFFER is `nil', the current buffer is assumed.
-
- - Function: bobp &optional buffer
- This function returns `t' if point is at the beginning of the
- buffer. If narrowing is in effect, this means the beginning of the
- accessible portion of the text. If optional argument BUFFER is
- `nil', the current buffer is assumed. See also `point-min' in
- *Note Point::.
-
- - Function: eobp &optional buffer
- This function returns `t' if point is at the end of the buffer.
- If narrowing is in effect, this means the end of accessible
- portion of the text. If optional argument BUFFER is `nil', the
- current buffer is assumed. See also `point-max' in *Note Point::.
-
- - Function: bolp &optional buffer
- This function returns `t' if point is at the beginning of a line.
- If optional argument BUFFER is `nil', the current buffer is
- assumed. *Note Text Lines::. The beginning of the buffer (or its
- accessible portion) always counts as the beginning of a line.
-
- - Function: eolp &optional buffer
- This function returns `t' if point is at the end of a line. The
- end of the buffer is always considered the end of a line. If
- optional argument BUFFER is `nil', the current buffer is assumed.
- The end of the buffer (or of its accessible portion) is always
- considered the end of a line.
-
-\1f
-File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
-
-Examining Buffer Contents
-=========================
-
- This section describes two functions that allow a Lisp program to
-convert any portion of the text in the buffer into a string.
-
- - Function: buffer-substring start end &optional buffer
- - Function: buffer-string start end &optional buffer
- These functions are equivalent and return a string containing a
- copy of the text of the region defined by positions START and END
- in the buffer. If the arguments are not positions in the
- accessible portion of the buffer, `buffer-substring' signals an
- `args-out-of-range' error. If optional argument BUFFER is `nil',
- the current buffer is assumed.
-
- If the region delineated by START and END contains duplicable
- extents, they will be remembered in the string. *Note Duplicable
- Extents::.
-
- It is not necessary for START to be less than END; the arguments
- can be given in either order. But most often the smaller argument
- is written first.
-
- ---------- Buffer: foo ----------
- This is the contents of buffer foo
-
- ---------- Buffer: foo ----------
-
- (buffer-substring 1 10)
- => "This is t"
- (buffer-substring (point-max) 10)
- => "he contents of buffer foo
- "
-
-\1f
-File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
-
-Comparing Text
-==============
-
- This function lets you compare portions of the text in a buffer,
-without copying them into strings first.
-
- - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
- start2 end2
- This function lets you compare two substrings of the same buffer
- or two different buffers. The first three arguments specify one
- substring, giving a buffer and two positions within the buffer.
- The last three arguments specify the other substring in the same
- way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
- the current buffer.
-
- The value is negative if the first substring is less, positive if
- the first is greater, and zero if they are equal. The absolute
- value of the result is one plus the index of the first differing
- characters within the substrings.
-
- This function ignores case when comparing characters if
- `case-fold-search' is non-`nil'. It always ignores text
- properties.
-
- Suppose the current buffer contains the text `foobarbar
- haha!rara!'; then in this example the two substrings are `rbar '
- and `rara!'. The value is 2 because the first substring is greater
- at the second character.
-
- (compare-buffer-substring nil 6 11 nil 16 21)
- => 2
-
-\1f
-File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
-
-Inserting Text
-==============
-
- "Insertion" means adding new text to a buffer. The inserted text
-goes at point--between the character before point and the character
-after point.
-
- Insertion relocates markers that point at positions after the
-insertion point, so that they stay with the surrounding text (*note
-Markers::). When a marker points at the place of insertion, insertion
-normally doesn't relocate the marker, so that it points to the
-beginning of the inserted text; however, certain special functions such
-as `insert-before-markers' relocate such markers to point after the
-inserted text.
-
- Some insertion functions leave point before the inserted text, while
-other functions leave it after. We call the former insertion "after
-point" and the latter insertion "before point".
-
- If a string with non-`nil' extent data is inserted, the remembered
-extents will also be inserted. *Note Duplicable Extents::.
-
- Insertion functions signal an error if the current buffer is
-read-only.
-
- These functions copy text characters from strings and buffers along
-with their properties. The inserted characters have exactly the same
-properties as the characters they were copied from. By contrast,
-characters specified as separate arguments, not part of a string or
-buffer, inherit their text properties from the neighboring text.
-
- - Function: insert &rest args
- This function inserts the strings and/or characters ARGS into the
- current buffer, at point, moving point forward. In other words, it
- inserts the text before point. An error is signaled unless all
- ARGS are either strings or characters. The value is `nil'.
-
- - Function: insert-before-markers &rest args
- This function inserts the strings and/or characters ARGS into the
- current buffer, at point, moving point forward. An error is
- signaled unless all ARGS are either strings or characters. The
- value is `nil'.
-
- This function is unlike the other insertion functions in that it
- relocates markers initially pointing at the insertion point, to
- point after the inserted text.
-
- - Function: insert-string string &optional buffer
- This function inserts STRING into BUFFER before point. BUFFER
- defaults to the current buffer if omitted. This function is
- chiefly useful if you want to insert a string in a buffer other
- than the current one (otherwise you could just use `insert').
-
- - Function: insert-char character count &optional buffer
- This function inserts COUNT instances of CHARACTER into BUFFER
- before point. COUNT must be a number, and CHARACTER must be a
- character. The value is `nil'. If optional argument BUFFER is
- `nil', the current buffer is assumed. (In FSF Emacs, the third
- argument is called INHERIT and refers to text properties.)
-
- - Function: insert-buffer-substring from-buffer-or-name &optional
- start end
- This function inserts a portion of buffer FROM-BUFFER-OR-NAME
- (which must already exist) into the current buffer before point.
- The text inserted is the region from START and END. (These
- arguments default to the beginning and end of the accessible
- portion of that buffer.) This function returns `nil'.
-
- In this example, the form is executed with buffer `bar' as the
- current buffer. We assume that buffer `bar' is initially empty.
-
- ---------- Buffer: foo ----------
- We hold these truths to be self-evident, that all
- ---------- Buffer: foo ----------
-
- (insert-buffer-substring "foo" 1 20)
- => nil
-
- ---------- Buffer: bar ----------
- We hold these truth-!-
- ---------- Buffer: bar ----------
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
+
+The Mark
+========
+
+ One special marker in each buffer is designated "the mark". It
+records a position for the user for the sake of commands such as `C-w'
+and `C-x <TAB>'. Lisp programs should set the mark only to values that
+have a potential use to the user, and never for their own internal
+purposes. For example, the `replace-regexp' command sets the mark to
+the value of point before doing any replacements, because this enables
+the user to move back there conveniently after the replace is finished.
+
+ Once the mark "exists" in a buffer, it normally never ceases to
+exist. However, it may become "inactive", and usually does so after
+each command (other than simple motion commands and some commands that
+explicitly activate the mark). When the mark is active, the region
+between point and the mark is called the "active region" and is
+highlighted specially.
+
+ Many commands are designed so that when called interactively they
+operate on the text between point and the mark. Such commands work
+only when an active region exists, i.e. when the mark is active. (The
+reason for this is to prevent you from accidentally deleting or
+changing large chunks of your text.) If you are writing such a command,
+don't examine the mark directly; instead, use `interactive' with the
+`r' specification. This provides the values of point and the mark as
+arguments to the command in an interactive call, but permits other Lisp
+programs to specify arguments explicitly, and automatically signals an
+error if the command is called interactively when no active region
+exists. *Note Interactive Codes::.
+
+ Each buffer has its own value of the mark that is independent of the
+value of the mark in other buffers. (When a buffer is created, the mark
+exists but does not point anywhere. We consider this state as "the
+absence of a mark in that buffer.") However, only one active region can
+exist at a time. Activating the mark in one buffer automatically
+deactivates an active mark in any other buffer. Note that the user can
+explicitly activate a mark at any time by using the command
+`activate-region' (normally bound to `M-C-z') or by using the command
+`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
+side effect of activating the mark.
+
+ Some people do not like active regions, so they disable this behavior
+by setting the variable `zmacs-regions' to `nil'. This makes the mark
+always active (except when a buffer is just created and the mark points
+nowhere), and turns off the highlighting of the region between point
+and the mark. Commands that explicitly retrieve the value of the mark
+should make sure that they behave correctly and consistently
+irrespective of the setting of `zmacs-regions'; some primitives are
+provided to ensure this behavior.
+
+ In addition to the mark, each buffer has a "mark ring" which is a
+list of markers containing previous values of the mark. When editing
+commands change the mark, they should normally save the old value of the
+mark on the mark ring. The variable `mark-ring-max' specifies the
+maximum number of entries in the mark ring; once the list becomes this
+long, adding a new element deletes the last element.
+
+ - Function: mark &optional force buffer
+ This function returns BUFFER's mark position as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ If the mark is inactive, `mark' normally returns `nil'. However,
+ if FORCE is non-`nil', then `mark' returns the mark position
+ anyway--or `nil', if the mark is not yet set for the buffer.
+
+ (Remember that if ZMACS-REGIONS is `nil', the mark is always
+ active as long as it exists, and the FORCE argument will have no
+ effect.)
+
+ If you are using this in an editing command, you are most likely
+ making a mistake; see the documentation of `set-mark' below.
+
+ - Function: mark-marker inactive-p buffer
+ This function returns BUFFER's mark. BUFFER defaults to the
+ current buffer if omitted. This is the very marker that records
+ the mark location inside XEmacs, not a copy. Therefore, changing
+ this marker's position will directly affect the position of the
+ mark. Don't do it unless that is the effect you want.
+
+ If the mark is inactive, `mark-marker' normally returns `nil'.
+ However, if FORCE is non-`nil', then `mark-marker' returns the
+ mark anyway.
+ (setq m (mark-marker))
+ => #<marker at 3420 in markers.texi>
+ (set-marker m 100)
+ => #<marker at 100 in markers.texi>
+ (mark-marker)
+ => #<marker at 100 in markers.texi>
+
+ Like any marker, this marker can be set to point at any buffer you
+ like. We don't recommend that you make it point at any buffer
+ other than the one of which it is the mark. If you do, it will
+ yield perfectly consistent, but rather odd, results.
+
+ - Function: set-mark position &optional buffer
+ This function sets `buffer''s mark to POSITION, and activates the
+ mark. BUFFER defaults to the current buffer if omitted. The old
+ value of the mark is _not_ pushed onto the mark ring.
+
+ *Please note:* Use this function only if you want the user to see
+ that the mark has moved, and you want the previous mark position to
+ be lost. Normally, when a new mark is set, the old one should go
+ on the `mark-ring'. For this reason, most applications should use
+ `push-mark' and `pop-mark', not `set-mark'.
+
+ Novice XEmacs Lisp programmers often try to use the mark for the
+ wrong purposes. The mark saves a location for the user's
+ convenience. An editing command should not alter the mark unless
+ altering the mark is part of the user-level functionality of the
+ command. (And, in that case, this effect should be documented.)
+ To remember a location for internal use in the Lisp program, store
+ it in a Lisp variable. For example:
+
+ (let ((beg (point)))
+ (forward-line 1)
+ (delete-region beg (point))).
+
+ - Command: exchange-point-and-mark &optional dont-activate-region
+ This function exchanges the positions of point and the mark. It
+ is intended for interactive use. The mark is also activated
+ unless DONT-ACTIVATE-REGION is non-`nil'.
+
+ - Function: push-mark &optional position nomsg activate buffer
+ This function sets BUFFER's mark to POSITION, and pushes a copy of
+ the previous mark onto `mark-ring'. BUFFER defaults to the
+ current buffer if omitted. If POSITION is `nil', then the value
+ of point is used. `push-mark' returns `nil'.
+
+ If the last global mark pushed was not in BUFFER, also push
+ POSITION on the global mark ring (see below).
+
+ The function `push-mark' normally _does not_ activate the mark.
+ To do that, specify `t' for the argument ACTIVATE.
+
+ A `Mark set' message is displayed unless NOMSG is non-`nil'.
+
+ - Function: pop-mark
+ This function pops off the top element of `mark-ring' and makes
+ that mark become the buffer's actual mark. This does not move
+ point in the buffer, and it does nothing if `mark-ring' is empty.
+ It deactivates the mark.
+
+ The return value is not meaningful.
+
+ - Variable: mark-ring
+ The value of this buffer-local variable is the list of saved former
+ marks of the current buffer, most recent first.
+
+ mark-ring
+ => (#<marker at 11050 in markers.texi>
+ #<marker at 10832 in markers.texi>
+ ...)
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of `mark-ring'. If
+ more marks than this are pushed onto the `mark-ring', `push-mark'
+ discards an old mark when it adds a new one.
+
+ In additional to a per-buffer mark ring, there is a "global mark
+ring". Marks are pushed onto the global mark ring the first time you
+set a mark after switching buffers.
+
+ - Variable: global-mark-ring
+ The value of this variable is the list of saved former global
+ marks, most recent first.
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of
+ `global-mark-ring'. If more marks than this are pushed onto the
+ `global-mark-ring', `push-mark' discards an old mark when it adds
+ a new one.
+
+ - Command: pop-global-mark
+ This function pops a mark off the global mark ring and jumps to
+ that location.
+
+\1f
+File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
+
+The Region
+==========
+
+ The text between point and the mark is known as "the region".
+Various functions operate on text delimited by point and the mark, but
+only those functions specifically related to the region itself are
+described here.
+
+ When `zmacs-regions' is non-`nil' (this is the default), the concept
+of an "active region" exists. The region is active when the
+corresponding mark is active. Note that only one active region at a
+time can exist--i.e. only one buffer's region is active at a time.
+*Note The Mark::, for more information about active regions.
+
+ - User Option: zmacs-regions
+ If non-`nil' (the default), active regions are used. *Note The
+ Mark::, for a detailed explanation of what this means.
+
+ A number of functions are provided for explicitly determining the
+bounds of the region and whether it is active. Few programs need to use
+these functions, however. A command designed to operate on a region
+should normally use `interactive' with the `r' specification to find
+the beginning and end of the region. This lets other Lisp programs
+specify the bounds explicitly as arguments and automatically respects
+the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
+
+ - Function: region-beginning &optional buffer
+ This function returns the position of the beginning of BUFFER's
+ region (as an integer). This is the position of either point or
+ the mark, whichever is smaller. BUFFER defaults to the current
+ buffer if omitted.
+
+ If the mark does not point anywhere, an error is signaled. Note
+ that this function ignores whether the region is active.
+
+ - Function: region-end &optional buffer
+ This function returns the position of the end of BUFFER's region
+ (as an integer). This is the position of either point or the mark,
+ whichever is larger. BUFFER defaults to the current buffer if
+ omitted.
+
+ If the mark does not point anywhere, an error is signaled. Note
+ that this function ignores whether the region is active.
+
+ - Function: region-exists-p
+ This function is non-`nil' if the region exists. If active regions
+ are in use (i.e. `zmacs-regions' is true), this means that the
+ region is active. Otherwise, this means that the user has pushed
+ a mark in this buffer at some point in the past. If this function
+ returns `nil', a function that uses the `r' interactive
+ specification will cause an error when called interactively.
+
+ - Function: region-active-p
+ If `zmacs-regions' is true, this is equivalent to
+ `region-exists-p'. Otherwise, this function always returns false.
+ This function is used by commands such as
+ `fill-paragraph-or-region' and `capitalize-region-or-word', which
+ operate either on the active region or on something else (e.g. the
+ word or paragraph at point).
+
+ - Variable: zmacs-region-stays
+ If a command sets this variable to true, the currently active
+ region will remain activated when the command finishes. (Normally
+ the region is deactivated when each command terminates.) If
+ ZMACS-REGIONS is false, however, this has no effect. Under normal
+ circumstances, you do not need to set this; use the interactive
+ specification `_' instead, if you want the region to remain active.
+
+ - Function: zmacs-activate-region
+ This function activates the region in the current buffer (this is
+ equivalent to activating the current buffer's mark). This will
+ normally also highlight the text in the active region and set
+ ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
+ this function has no effect.)
+
+ - Function: zmacs-deactivate-region
+ This function deactivates the region in the current buffer (this is
+ equivalent to deactivating the current buffer's mark). This will
+ normally also unhighlight the text in the active region and set
+ ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
+ this function has no effect.)
+
+ - Function: zmacs-update-region
+ This function updates the active region, if it's currently active.
+ (If there is no active region, this function does nothing.) This
+ has the effect of updating the highlighting on the text in the
+ region; but you should never need to call this except under rather
+ strange circumstances. The command loop automatically calls it
+ when appropriate. Calling this function will call the hook
+ `zmacs-update-region-hook', if the region is active.
+
+ - Variable: zmacs-activate-region-hook
+ This normal hook is called when a region becomes active. (Usually
+ this happens as a result of a command that activates the region,
+ such as `set-mark-command', `activate-region', or
+ `exchange-point-and-mark'.) Note that calling
+ `zmacs-activate-region' will call this hook, even if the region is
+ already active. If ZMACS-REGIONS is false, however, this hook
+ will never get called under any circumstances.
+
+ - Variable: zmacs-deactivate-region-hook
+ This normal hook is called when an active region becomes inactive.
+ (Calling `zmacs-deactivate-region' when the region is inactive will
+ _not_ cause this hook to be called.) If ZMACS-REGIONS is false,
+ this hook will never get called.
+
+ - Variable: zmacs-update-region-hook
+ This normal hook is called when an active region is "updated" by
+ `zmacs-update-region'. This normally gets called at the end of
+ each command that sets ZMACS-REGION-STAYS to `t', indicating that
+ the region should remain activated. The motion commands do this.
+
+\1f
+File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
+
+Text
+****
+
+ This chapter describes the functions that deal with the text in a
+buffer. Most examine, insert, or delete text in the current buffer,
+often in the vicinity of point. Many are interactive. All the
+functions that change the text provide for undoing the changes (*note
+Undo::).
+
+ Many text-related functions operate on a region of text defined by
+two buffer positions passed in arguments named START and END. These
+arguments should be either markers (*note Markers::) or numeric
+character positions (*note Positions::). The order of these arguments
+does not matter; it is all right for START to be the end of the region
+and END the beginning. For example, `(delete-region 1 10)' and
+`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
+signaled if either START or END is outside the accessible portion of
+the buffer. In an interactive call, point and the mark are used for
+these arguments.
+
+ Throughout this chapter, "text" refers to the characters in the
+buffer, together with their properties (when relevant).
+
+* Menu:
+
+* Near Point:: Examining text in the vicinity of point.
+* Buffer Contents:: Examining text in a general fashion.
+* Comparing Text:: Comparing substrings of buffers.
+* Insertion:: Adding new text to a buffer.
+* Commands for Insertion:: User-level commands to insert text.
+* Deletion:: Removing text from a buffer.
+* User-Level Deletion:: User-level commands to delete text.
+* The Kill Ring:: Where removed text sometimes is saved for later use.
+* Undo:: Undoing changes to the text of a buffer.
+* Maintaining Undo:: How to enable and disable undo information.
+ How to control how much information is kept.
+* Filling:: Functions for explicit filling.
+* Margins:: How to specify margins for filling commands.
+* Auto Filling:: How auto-fill mode is implemented to break lines.
+* Sorting:: Functions for sorting parts of the buffer.
+* Columns:: Computing horizontal positions, and using them.
+* Indentation:: Functions to insert or adjust indentation.
+* Case Changes:: Case conversion of parts of the buffer.
+* Text Properties:: Assigning Lisp property lists to text characters.
+* Substitution:: Replacing a given character wherever it appears.
+* Registers:: How registers are implemented. Accessing the text or
+ position stored in a register.
+* Transposition:: Swapping two portions of a buffer.
+* Change Hooks:: Supplying functions to be run when text is changed.
+* Transformations:: MD5 and base64 support.
+
+\1f
+File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
+
+Examining Text Near Point
+=========================
+
+ Many functions are provided to look at the characters around point.
+Several simple functions are described here. See also `looking-at' in
+*Note Regexp Search::.
+
+ Many of these functions take an optional BUFFER argument. In all
+such cases, the current buffer will be used if this argument is
+omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
+usually did not have these optional BUFFER arguments and always
+operated on the current buffer.)
+
+ - Function: char-after &optional position buffer
+ This function returns the character in the buffer at (i.e.,
+ immediately after) position POSITION. If POSITION is out of range
+ for this purpose, either before the beginning of the buffer, or at
+ or beyond the end, then the value is `nil'. The default for
+ POSITION is point. If optional argument BUFFER is `nil', the
+ current buffer is assumed.
+
+ In the following example, assume that the first character in the
+ buffer is `@':
+
+ (char-to-string (char-after 1))
+ => "@"
+
+ - Function: char-before &optional position buffer
+ This function returns the character in the current buffer
+ immediately before position POSITION. If POSITION is out of range
+ for this purpose, either at or before the beginning of the buffer,
+ or beyond the end, then the value is `nil'. The default for
+ POSITION is point. If optional argument BUFFER is `nil', the
+ current buffer is assumed.
+
+ - Function: following-char &optional buffer
+ This function returns the character following point in the buffer.
+ This is similar to `(char-after (point))'. However, if point is at
+ the end of the buffer, then the result of `following-char' is 0.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed.
+
+ Remember that point is always between characters, and the terminal
+ cursor normally appears over the character following point.
+ Therefore, the character returned by `following-char' is the
+ character the cursor is over.
+
+ In this example, point is between the `a' and the `c'.
+
+ ---------- Buffer: foo ----------
+ Gentlemen may cry ``Pea-!-ce! Peace!,''
+ but there is no peace.
+ ---------- Buffer: foo ----------
+
+ (char-to-string (preceding-char))
+ => "a"
+ (char-to-string (following-char))
+ => "c"
+
+ - Function: preceding-char &optional buffer
+ This function returns the character preceding point in the buffer.
+ See above, under `following-char', for an example. If point is at
+ the beginning of the buffer, `preceding-char' returns 0. If
+ optional argument BUFFER is `nil', the current buffer is assumed.
+
+ - Function: bobp &optional buffer
+ This function returns `t' if point is at the beginning of the
+ buffer. If narrowing is in effect, this means the beginning of the
+ accessible portion of the text. If optional argument BUFFER is
+ `nil', the current buffer is assumed. See also `point-min' in
+ *Note Point::.
+
+ - Function: eobp &optional buffer
+ This function returns `t' if point is at the end of the buffer.
+ If narrowing is in effect, this means the end of accessible
+ portion of the text. If optional argument BUFFER is `nil', the
+ current buffer is assumed. See also `point-max' in *Note Point::.
+
+ - Function: bolp &optional buffer
+ This function returns `t' if point is at the beginning of a line.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed. *Note Text Lines::. The beginning of the buffer (or its
+ accessible portion) always counts as the beginning of a line.
+
+ - Function: eolp &optional buffer
+ This function returns `t' if point is at the end of a line. The
+ end of the buffer is always considered the end of a line. If
+ optional argument BUFFER is `nil', the current buffer is assumed.
+ The end of the buffer (or of its accessible portion) is always
+ considered the end of a line.
+
+\1f
+File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
+
+Examining Buffer Contents
+=========================
+
+ This section describes two functions that allow a Lisp program to
+convert any portion of the text in the buffer into a string.
+
+ - Function: buffer-substring start end &optional buffer
+ - Function: buffer-string start end &optional buffer
+ These functions are equivalent and return a string containing a
+ copy of the text of the region defined by positions START and END
+ in the buffer. If the arguments are not positions in the
+ accessible portion of the buffer, `buffer-substring' signals an
+ `args-out-of-range' error. If optional argument BUFFER is `nil',
+ the current buffer is assumed.
+
+ If the region delineated by START and END contains duplicable
+ extents, they will be remembered in the string. *Note Duplicable
+ Extents::.
+
+ It is not necessary for START to be less than END; the arguments
+ can be given in either order. But most often the smaller argument
+ is written first.
+
+ ---------- Buffer: foo ----------
+ This is the contents of buffer foo
+
+ ---------- Buffer: foo ----------
+
+ (buffer-substring 1 10)
+ => "This is t"
+ (buffer-substring (point-max) 10)
+ => "he contents of buffer foo
+ "
+
+\1f
+File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
+
+Comparing Text
+==============
+
+ This function lets you compare portions of the text in a buffer,
+without copying them into strings first.
+
+ - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
+ start2 end2
+ This function lets you compare two substrings of the same buffer
+ or two different buffers. The first three arguments specify one
+ substring, giving a buffer and two positions within the buffer.
+ The last three arguments specify the other substring in the same
+ way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
+ the current buffer.
+
+ The value is negative if the first substring is less, positive if
+ the first is greater, and zero if they are equal. The absolute
+ value of the result is one plus the index of the first differing
+ characters within the substrings.
+
+ This function ignores case when comparing characters if
+ `case-fold-search' is non-`nil'. It always ignores text
+ properties.
+
+ Suppose the current buffer contains the text `foobarbar
+ haha!rara!'; then in this example the two substrings are `rbar '
+ and `rara!'. The value is 2 because the first substring is greater
+ at the second character.
+
+ (compare-buffer-substring nil 6 11 nil 16 21)
+ => 2
+
+\1f
+File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
+
+Inserting Text
+==============
+
+ "Insertion" means adding new text to a buffer. The inserted text
+goes at point--between the character before point and the character
+after point.
+
+ Insertion relocates markers that point at positions after the
+insertion point, so that they stay with the surrounding text (*note
+Markers::). When a marker points at the place of insertion, insertion
+normally doesn't relocate the marker, so that it points to the
+beginning of the inserted text; however, certain special functions such
+as `insert-before-markers' relocate such markers to point after the
+inserted text.
+
+ Some insertion functions leave point before the inserted text, while
+other functions leave it after. We call the former insertion "after
+point" and the latter insertion "before point".
+
+ If a string with non-`nil' extent data is inserted, the remembered
+extents will also be inserted. *Note Duplicable Extents::.
+
+ Insertion functions signal an error if the current buffer is
+read-only.
+
+ These functions copy text characters from strings and buffers along
+with their properties. The inserted characters have exactly the same
+properties as the characters they were copied from. By contrast,
+characters specified as separate arguments, not part of a string or
+buffer, inherit their text properties from the neighboring text.
+
+ - Function: insert &rest args
+ This function inserts the strings and/or characters ARGS into the
+ current buffer, at point, moving point forward. In other words, it
+ inserts the text before point. An error is signaled unless all
+ ARGS are either strings or characters. The value is `nil'.
+
+ - Function: insert-before-markers &rest args
+ This function inserts the strings and/or characters ARGS into the
+ current buffer, at point, moving point forward. An error is
+ signaled unless all ARGS are either strings or characters. The
+ value is `nil'.
+
+ This function is unlike the other insertion functions in that it
+ relocates markers initially pointing at the insertion point, to
+ point after the inserted text.
+
+ - Function: insert-string string &optional buffer
+ This function inserts STRING into BUFFER before point. BUFFER
+ defaults to the current buffer if omitted. This function is
+ chiefly useful if you want to insert a string in a buffer other
+ than the current one (otherwise you could just use `insert').
+
+ - Function: insert-char character count &optional buffer
+ This function inserts COUNT instances of CHARACTER into BUFFER
+ before point. COUNT must be a number, and CHARACTER must be a
+ character. The value is `nil'. If optional argument BUFFER is
+ `nil', the current buffer is assumed. (In FSF Emacs, the third
+ argument is called INHERIT and refers to text properties.)
+
+ - Function: insert-buffer-substring from-buffer-or-name &optional
+ start end
+ This function inserts a portion of buffer FROM-BUFFER-OR-NAME
+ (which must already exist) into the current buffer before point.
+ The text inserted is the region from START and END. (These
+ arguments default to the beginning and end of the accessible
+ portion of that buffer.) This function returns `nil'.
+
+ In this example, the form is executed with buffer `bar' as the
+ current buffer. We assume that buffer `bar' is initially empty.
+
+ ---------- Buffer: foo ----------
+ We hold these truths to be self-evident, that all
+ ---------- Buffer: foo ----------
+
+ (insert-buffer-substring "foo" 1 20)
+ => nil
+
+ ---------- Buffer: bar ----------
+ We hold these truth-!-
+ ---------- Buffer: bar ----------
+
+\1f
File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
User-Level Insertion Commands
The normal use of this hook is to set the X server's primary
selection to the newly killed text.
-\1f
-File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
-
-Internals of the Kill Ring
---------------------------
-
- The variable `kill-ring' holds the kill ring contents, in the form
-of a list of strings. The most recent kill is always at the front of
-the list.
-
- The `kill-ring-yank-pointer' variable points to a link in the kill
-ring list, whose CAR is the text to yank next. We say it identifies
-the "front" of the ring. Moving `kill-ring-yank-pointer' to a
-different link is called "rotating the kill ring". We call the kill
-ring a "ring" because the functions that move the yank pointer wrap
-around from the end of the list to the beginning, or vice-versa.
-Rotation of the kill ring is virtual; it does not change the value of
-`kill-ring'.
-
- Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
-whose values are normally lists. The word "pointer" in the name of the
-`kill-ring-yank-pointer' indicates that the variable's purpose is to
-identify one element of the list for use by the next yank command.
-
- The value of `kill-ring-yank-pointer' is always `eq' to one of the
-links in the kill ring list. The element it identifies is the CAR of
-that link. Kill commands, which change the kill ring, also set this
-variable to the value of `kill-ring'. The effect is to rotate the ring
-so that the newly killed text is at the front.
-
- Here is a diagram that shows the variable `kill-ring-yank-pointer'
-pointing to the second entry in the kill ring `("some text" "a
-different piece of text" "yet older text")'.
-
- kill-ring kill-ring-yank-pointer
- | |
- | ___ ___ ---> ___ ___ ___ ___
- --> |___|___|------> |___|___|--> |___|___|--> nil
- | | |
- | | |
- | | -->"yet older text"
- | |
- | --> "a different piece of text"
- |
- --> "some text"
-
-This state of affairs might occur after `C-y' (`yank') immediately
-followed by `M-y' (`yank-pop').
-
- - Variable: kill-ring
- This variable holds the list of killed text sequences, most
- recently killed first.
-
- - Variable: kill-ring-yank-pointer
- This variable's value indicates which element of the kill ring is
- at the "front" of the ring for yanking. More precisely, the value
- is a tail of the value of `kill-ring', and its CAR is the kill
- string that `C-y' should yank.
-
- - User Option: kill-ring-max
- The value of this variable is the maximum length to which the kill
- ring can grow, before elements are thrown away at the end. The
- default value for `kill-ring-max' is 30.
-
-\1f
-File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
-
-Undo
-====
-
- Most buffers have an "undo list", which records all changes made to
-the buffer's text so that they can be undone. (The buffers that don't
-have one are usually special-purpose buffers for which XEmacs assumes
-that undoing is not useful.) All the primitives that modify the text
-in the buffer automatically add elements to the front of the undo list,
-which is in the variable `buffer-undo-list'.
-
- - Variable: buffer-undo-list
- This variable's value is the undo list of the current buffer. A
- value of `t' disables the recording of undo information.
-
- Here are the kinds of elements an undo list can have:
-
-`INTEGER'
- This kind of element records a previous value of point. Ordinary
- cursor motion does not get any sort of undo record, but deletion
- commands use these entries to record where point was before the
- command.
-
-`(BEG . END)'
- This kind of element indicates how to delete text that was
- inserted. Upon insertion, the text occupied the range BEG-END in
- the buffer.
-
-`(TEXT . POSITION)'
- This kind of element indicates how to reinsert text that was
- deleted. The deleted text itself is the string TEXT. The place to
- reinsert it is `(abs POSITION)'.
-
-`(t HIGH . LOW)'
- This kind of element indicates that an unmodified buffer became
- modified. The elements HIGH and LOW are two integers, each
- recording 16 bits of the visited file's modification time as of
- when it was previously visited or saved. `primitive-undo' uses
- those values to determine whether to mark the buffer as unmodified
- once again; it does so only if the file's modification time
- matches those numbers.
-
-`(nil PROPERTY VALUE BEG . END)'
- This kind of element records a change in a text property. Here's
- how you might undo the change:
-
- (put-text-property BEG END PROPERTY VALUE)
-
-`POSITION'
- This element indicates where point was at an earlier time.
- Undoing this element sets point to POSITION. Deletion normally
- creates an element of this kind as well as a reinsertion element.
-
-`nil'
- This element is a boundary. The elements between two boundaries
- are called a "change group"; normally, each change group
- corresponds to one keyboard command, and undo commands normally
- undo an entire group as a unit.
-
- - Function: undo-boundary
- This function places a boundary element in the undo list. The undo
- command stops at such a boundary, and successive undo commands undo
- to earlier and earlier boundaries. This function returns `nil'.
-
- The editor command loop automatically creates an undo boundary
- before each key sequence is executed. Thus, each undo normally
- undoes the effects of one command. Self-inserting input
- characters are an exception. The command loop makes a boundary
- for the first such character; the next 19 consecutive
- self-inserting input characters do not make boundaries, and then
- the 20th does, and so on as long as self-inserting characters
- continue.
-
- All buffer modifications add a boundary whenever the previous
- undoable change was made in some other buffer. This way, a
- command that modifies several buffers makes a boundary in each
- buffer it changes.
-
- Calling this function explicitly is useful for splitting the
- effects of a command into more than one unit. For example,
- `query-replace' calls `undo-boundary' after each replacement, so
- that the user can undo individual replacements one by one.
-
- - Function: primitive-undo count list
- This is the basic function for undoing elements of an undo list.
- It undoes the first COUNT elements of LIST, returning the rest of
- LIST. You could write this function in Lisp, but it is convenient
- to have it in C.
-
- `primitive-undo' adds elements to the buffer's undo list when it
- changes the buffer. Undo commands avoid confusion by saving the
- undo list value at the beginning of a sequence of undo operations.
- Then the undo operations use and update the saved value. The new
- elements added by undoing are not part of this saved value, so
- they don't interfere with continuing to undo.
-
-\1f
-File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
-
-Maintaining Undo Lists
-======================
-
- This section describes how to enable and disable undo information for
-a given buffer. It also explains how the undo list is truncated
-automatically so it doesn't get too big.
-
- Recording of undo information in a newly created buffer is normally
-enabled to start with; but if the buffer name starts with a space, the
-undo recording is initially disabled. You can explicitly enable or
-disable undo recording with the following two functions, or by setting
-`buffer-undo-list' yourself.
-
- - Command: buffer-enable-undo &optional buffer-or-name
- This command enables recording undo information for buffer
- BUFFER-OR-NAME, so that subsequent changes can be undone. If no
- argument is supplied, then the current buffer is used. This
- function does nothing if undo recording is already enabled in the
- buffer. It returns `nil'.
-
- In an interactive call, BUFFER-OR-NAME is the current buffer. You
- cannot specify any other buffer.
-
- - Function: buffer-disable-undo &optional buffer
- - Function: buffer-flush-undo &optional buffer
- This function discards the undo list of BUFFER, and disables
- further recording of undo information. As a result, it is no
- longer possible to undo either previous changes or any subsequent
- changes. If the undo list of BUFFER is already disabled, this
- function has no effect.
-
- This function returns `nil'. It cannot be called interactively.
-
- The name `buffer-flush-undo' is not considered obsolete, but the
- preferred name `buffer-disable-undo' is new as of Emacs versions
- 19.
-
- As editing continues, undo lists get longer and longer. To prevent
-them from using up all available memory space, garbage collection trims
-them back to size limits you can set. (For this purpose, the "size" of
-an undo list measures the cons cells that make up the list, plus the
-strings of deleted text.) Two variables control the range of acceptable
-sizes: `undo-limit' and `undo-strong-limit'.
-
- - Variable: undo-limit
- This is the soft limit for the acceptable size of an undo list.
- The change group at which this size is exceeded is the last one
- kept.
-
- - Variable: undo-strong-limit
- This is the upper limit for the acceptable size of an undo list.
- The change group at which this size is exceeded is discarded
- itself (along with all older change groups). There is one
- exception: the very latest change group is never discarded no
- matter how big it is.
-
-\1f
-File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
-
-Filling
-=======
-
- "Filling" means adjusting the lengths of lines (by moving the line
-breaks) so that they are nearly (but no greater than) a specified
-maximum width. Additionally, lines can be "justified", which means
-inserting spaces to make the left and/or right margins line up
-precisely. The width is controlled by the variable `fill-column'. For
-ease of reading, lines should be no longer than 70 or so columns.
-
- You can use Auto Fill mode (*note Auto Filling::) to fill text
-automatically as you insert it, but changes to existing text may leave
-it improperly filled. Then you must fill the text explicitly.
-
- Most of the commands in this section return values that are not
-meaningful. All the functions that do filling take note of the current
-left margin, current right margin, and current justification style
-(*note Margins::). If the current justification style is `none', the
-filling functions don't actually do anything.
-
- Several of the filling functions have an argument JUSTIFY. If it is
-non-`nil', that requests some kind of justification. It can be `left',
-`right', `full', or `center', to request a specific style of
-justification. If it is `t', that means to use the current
-justification style for this part of the text (see
-`current-justification', below).
-
- When you call the filling functions interactively, using a prefix
-argument implies the value `full' for JUSTIFY.
-
- - Command: fill-paragraph justify
- This command fills the paragraph at or after point. If JUSTIFY is
- non-`nil', each line is justified as well. It uses the ordinary
- paragraph motion commands to find paragraph boundaries. *Note
- Paragraphs: (xemacs)Paragraphs.
-
- - Command: fill-region start end &optional justify
- This command fills each of the paragraphs in the region from START
- to END. It justifies as well if JUSTIFY is non-`nil'.
-
- The variable `paragraph-separate' controls how to distinguish
- paragraphs. *Note Standard Regexps::.
-
- - Command: fill-individual-paragraphs start end &optional justify
- mail-flag
- This command fills each paragraph in the region according to its
- individual fill prefix. Thus, if the lines of a paragraph were
- indented with spaces, the filled paragraph will remain indented in
- the same fashion.
-
- The first two arguments, START and END, are the beginning and end
- of the region to be filled. The third and fourth arguments,
- JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
- paragraphs are justified as well as filled. If MAIL-FLAG is
- non-`nil', it means the function is operating on a mail message
- and therefore should not fill the header lines.
-
- Ordinarily, `fill-individual-paragraphs' regards each change in
- indentation as starting a new paragraph. If
- `fill-individual-varying-indent' is non-`nil', then only separator
- lines separate paragraphs. That mode can handle indented
- paragraphs with additional indentation on the first line.
-
- - User Option: fill-individual-varying-indent
- This variable alters the action of `fill-individual-paragraphs' as
- described above.
-
- - Command: fill-region-as-paragraph start end &optional justify
- This command considers a region of text as a paragraph and fills
- it. If the region was made up of many paragraphs, the blank lines
- between paragraphs are removed. This function justifies as well
- as filling when JUSTIFY is non-`nil'.
-
- In an interactive call, any prefix argument requests justification.
-
- In Adaptive Fill mode, which is enabled by default,
- `fill-region-as-paragraph' on an indented paragraph when there is
- no fill prefix uses the indentation of the second line of the
- paragraph as the fill prefix.
-
- - Command: justify-current-line how eop nosqueeze
- This command inserts spaces between the words of the current line
- so that the line ends exactly at `fill-column'. It returns `nil'.
-
- The argument HOW, if non-`nil' specifies explicitly the style of
- justification. It can be `left', `right', `full', `center', or
- `none'. If it is `t', that means to do follow specified
- justification style (see `current-justification', below). `nil'
- means to do full justification.
-
- If EOP is non-`nil', that means do left-justification when
- `current-justification' specifies full justification. This is used
- for the last line of a paragraph; even if the paragraph as a whole
- is fully justified, the last line should not be.
-
- If NOSQUEEZE is non-`nil', that means do not change interior
- whitespace.
-
- - User Option: default-justification
- This variable's value specifies the style of justification to use
- for text that doesn't specify a style with a text property. The
- possible values are `left', `right', `full', `center', or `none'.
- The default value is `left'.
-
- - Function: current-justification
- This function returns the proper justification style to use for
- filling the text around point.
-
- - Variable: fill-paragraph-function
- This variable provides a way for major modes to override the
- filling of paragraphs. If the value is non-`nil',
- `fill-paragraph' calls this function to do the work. If the
- function returns a non-`nil' value, `fill-paragraph' assumes the
- job is done, and immediately returns that value.
-
- The usual use of this feature is to fill comments in programming
- language modes. If the function needs to fill a paragraph in the
- usual way, it can do so as follows:
-
- (let ((fill-paragraph-function nil))
- (fill-paragraph arg))
-
- - Variable: use-hard-newlines
- If this variable is non-`nil', the filling functions do not delete
- newlines that have the `hard' text property. These "hard
- newlines" act as paragraph separators.
-
-\1f
-File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
-
-Margins for Filling
-===================
-
- - User Option: fill-prefix
- This variable specifies a string of text that appears at the
- beginning of normal text lines and should be disregarded when
- filling them. Any line that fails to start with the fill prefix
- is considered the start of a paragraph; so is any line that starts
- with the fill prefix followed by additional whitespace. Lines
- that start with the fill prefix but no additional whitespace are
- ordinary text lines that can be filled together. The resulting
- filled lines also start with the fill prefix.
-
- The fill prefix follows the left margin whitespace, if any.
-
- - User Option: fill-column
- This buffer-local variable specifies the maximum width of filled
- lines. Its value should be an integer, which is a number of
- columns. All the filling, justification and centering commands
- are affected by this variable, including Auto Fill mode (*note
- Auto Filling::).
-
- As a practical matter, if you are writing text for other people to
- read, you should set `fill-column' to no more than 70. Otherwise
- the line will be too long for people to read comfortably, and this
- can make the text seem clumsy.
-
- - Variable: default-fill-column
- The value of this variable is the default value for `fill-column'
- in buffers that do not override it. This is the same as
- `(default-value 'fill-column)'.
-
- The default value for `default-fill-column' is 70.
-
- - Command: set-left-margin from to margin
- This sets the `left-margin' property on the text from FROM to TO
- to the value MARGIN. If Auto Fill mode is enabled, this command
- also refills the region to fit the new margin.
-
- - Command: set-right-margin from to margin
- This sets the `right-margin' property on the text from FROM to TO
- to the value MARGIN. If Auto Fill mode is enabled, this command
- also refills the region to fit the new margin.
-
- - Function: current-left-margin
- This function returns the proper left margin value to use for
- filling the text around point. The value is the sum of the
- `left-margin' property of the character at the start of the
- current line (or zero if none), and the value of the variable
- `left-margin'.
-
- - Function: current-fill-column
- This function returns the proper fill column value to use for
- filling the text around point. The value is the value of the
- `fill-column' variable, minus the value of the `right-margin'
- property of the character after point.
-
- - Command: move-to-left-margin &optional n force
- This function moves point to the left margin of the current line.
- The column moved to is determined by calling the function
- `current-left-margin'. If the argument N is non-`nil',
- `move-to-left-margin' moves forward N-1 lines first.
-
- If FORCE is non-`nil', that says to fix the line's indentation if
- that doesn't match the left margin value.
-
- - Function: delete-to-left-margin from to
- This function removes left margin indentation from the text
- between FROM and TO. The amount of indentation to delete is
- determined by calling `current-left-margin'. In no case does this
- function delete non-whitespace.
-
- - Function: indent-to-left-margin
- This is the default `indent-line-function', used in Fundamental
- mode, Text mode, etc. Its effect is to adjust the indentation at
- the beginning of the current line to the value specified by the
- variable `left-margin'. This may involve either inserting or
- deleting whitespace.
-
- - Variable: left-margin
- This variable specifies the base left margin column. In
- Fundamental mode, <LFD> indents to this column. This variable
- automatically becomes buffer-local when set in any fashion.
-
-\1f
-File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
-
-Auto Filling
-============
-
- Auto Fill mode is a minor mode that fills lines automatically as text
-is inserted. This section describes the hook used by Auto Fill mode.
-For a description of functions that you can call explicitly to fill and
-justify existing text, see *Note Filling::.
-
- Auto Fill mode also enables the functions that change the margins and
-justification style to refill portions of the text. *Note Margins::.
-
- - Variable: auto-fill-function
- The value of this variable should be a function (of no arguments)
- to be called after self-inserting a space or a newline. It may be
- `nil', in which case nothing special is done in that case.
-
- The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
- mode is enabled. That is a function whose sole purpose is to
- implement the usual strategy for breaking a line.
-
- In older Emacs versions, this variable was named
- `auto-fill-hook', but since it is not called with the
- standard convention for hooks, it was renamed to
- `auto-fill-function' in version 19.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
+
+Internals of the Kill Ring
+--------------------------
+
+ The variable `kill-ring' holds the kill ring contents, in the form
+of a list of strings. The most recent kill is always at the front of
+the list.
+
+ The `kill-ring-yank-pointer' variable points to a link in the kill
+ring list, whose CAR is the text to yank next. We say it identifies
+the "front" of the ring. Moving `kill-ring-yank-pointer' to a
+different link is called "rotating the kill ring". We call the kill
+ring a "ring" because the functions that move the yank pointer wrap
+around from the end of the list to the beginning, or vice-versa.
+Rotation of the kill ring is virtual; it does not change the value of
+`kill-ring'.
+
+ Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
+whose values are normally lists. The word "pointer" in the name of the
+`kill-ring-yank-pointer' indicates that the variable's purpose is to
+identify one element of the list for use by the next yank command.
+
+ The value of `kill-ring-yank-pointer' is always `eq' to one of the
+links in the kill ring list. The element it identifies is the CAR of
+that link. Kill commands, which change the kill ring, also set this
+variable to the value of `kill-ring'. The effect is to rotate the ring
+so that the newly killed text is at the front.
+
+ Here is a diagram that shows the variable `kill-ring-yank-pointer'
+pointing to the second entry in the kill ring `("some text" "a
+different piece of text" "yet older text")'.
+
+ kill-ring kill-ring-yank-pointer
+ | |
+ | ___ ___ ---> ___ ___ ___ ___
+ --> |___|___|------> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ | | -->"yet older text"
+ | |
+ | --> "a different piece of text"
+ |
+ --> "some text"
+
+This state of affairs might occur after `C-y' (`yank') immediately
+followed by `M-y' (`yank-pop').
+
+ - Variable: kill-ring
+ This variable holds the list of killed text sequences, most
+ recently killed first.
+
+ - Variable: kill-ring-yank-pointer
+ This variable's value indicates which element of the kill ring is
+ at the "front" of the ring for yanking. More precisely, the value
+ is a tail of the value of `kill-ring', and its CAR is the kill
+ string that `C-y' should yank.
+
+ - User Option: kill-ring-max
+ The value of this variable is the maximum length to which the kill
+ ring can grow, before elements are thrown away at the end. The
+ default value for `kill-ring-max' is 30.
+
+\1f
+File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
+
+Undo
+====
+
+ Most buffers have an "undo list", which records all changes made to
+the buffer's text so that they can be undone. (The buffers that don't
+have one are usually special-purpose buffers for which XEmacs assumes
+that undoing is not useful.) All the primitives that modify the text
+in the buffer automatically add elements to the front of the undo list,
+which is in the variable `buffer-undo-list'.
+
+ - Variable: buffer-undo-list
+ This variable's value is the undo list of the current buffer. A
+ value of `t' disables the recording of undo information.
+
+ Here are the kinds of elements an undo list can have:
+
+`INTEGER'
+ This kind of element records a previous value of point. Ordinary
+ cursor motion does not get any sort of undo record, but deletion
+ commands use these entries to record where point was before the
+ command.
+
+`(BEG . END)'
+ This kind of element indicates how to delete text that was
+ inserted. Upon insertion, the text occupied the range BEG-END in
+ the buffer.
+
+`(TEXT . POSITION)'
+ This kind of element indicates how to reinsert text that was
+ deleted. The deleted text itself is the string TEXT. The place to
+ reinsert it is `(abs POSITION)'.
+
+`(t HIGH . LOW)'
+ This kind of element indicates that an unmodified buffer became
+ modified. The elements HIGH and LOW are two integers, each
+ recording 16 bits of the visited file's modification time as of
+ when it was previously visited or saved. `primitive-undo' uses
+ those values to determine whether to mark the buffer as unmodified
+ once again; it does so only if the file's modification time
+ matches those numbers.
+
+`(nil PROPERTY VALUE BEG . END)'
+ This kind of element records a change in a text property. Here's
+ how you might undo the change:
+
+ (put-text-property BEG END PROPERTY VALUE)
+
+`POSITION'
+ This element indicates where point was at an earlier time.
+ Undoing this element sets point to POSITION. Deletion normally
+ creates an element of this kind as well as a reinsertion element.
+
+`nil'
+ This element is a boundary. The elements between two boundaries
+ are called a "change group"; normally, each change group
+ corresponds to one keyboard command, and undo commands normally
+ undo an entire group as a unit.
+
+ - Function: undo-boundary
+ This function places a boundary element in the undo list. The undo
+ command stops at such a boundary, and successive undo commands undo
+ to earlier and earlier boundaries. This function returns `nil'.
+
+ The editor command loop automatically creates an undo boundary
+ before each key sequence is executed. Thus, each undo normally
+ undoes the effects of one command. Self-inserting input
+ characters are an exception. The command loop makes a boundary
+ for the first such character; the next 19 consecutive
+ self-inserting input characters do not make boundaries, and then
+ the 20th does, and so on as long as self-inserting characters
+ continue.
+
+ All buffer modifications add a boundary whenever the previous
+ undoable change was made in some other buffer. This way, a
+ command that modifies several buffers makes a boundary in each
+ buffer it changes.
+
+ Calling this function explicitly is useful for splitting the
+ effects of a command into more than one unit. For example,
+ `query-replace' calls `undo-boundary' after each replacement, so
+ that the user can undo individual replacements one by one.
+
+ - Function: primitive-undo count list
+ This is the basic function for undoing elements of an undo list.
+ It undoes the first COUNT elements of LIST, returning the rest of
+ LIST. You could write this function in Lisp, but it is convenient
+ to have it in C.
+
+ `primitive-undo' adds elements to the buffer's undo list when it
+ changes the buffer. Undo commands avoid confusion by saving the
+ undo list value at the beginning of a sequence of undo operations.
+ Then the undo operations use and update the saved value. The new
+ elements added by undoing are not part of this saved value, so
+ they don't interfere with continuing to undo.
+
+\1f
+File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
+
+Maintaining Undo Lists
+======================
+
+ This section describes how to enable and disable undo information for
+a given buffer. It also explains how the undo list is truncated
+automatically so it doesn't get too big.
+
+ Recording of undo information in a newly created buffer is normally
+enabled to start with; but if the buffer name starts with a space, the
+undo recording is initially disabled. You can explicitly enable or
+disable undo recording with the following two functions, or by setting
+`buffer-undo-list' yourself.
+
+ - Command: buffer-enable-undo &optional buffer-or-name
+ This command enables recording undo information for buffer
+ BUFFER-OR-NAME, so that subsequent changes can be undone. If no
+ argument is supplied, then the current buffer is used. This
+ function does nothing if undo recording is already enabled in the
+ buffer. It returns `nil'.
+
+ In an interactive call, BUFFER-OR-NAME is the current buffer. You
+ cannot specify any other buffer.
+
+ - Function: buffer-disable-undo &optional buffer
+ - Function: buffer-flush-undo &optional buffer
+ This function discards the undo list of BUFFER, and disables
+ further recording of undo information. As a result, it is no
+ longer possible to undo either previous changes or any subsequent
+ changes. If the undo list of BUFFER is already disabled, this
+ function has no effect.
+
+ This function returns `nil'. It cannot be called interactively.
+
+ The name `buffer-flush-undo' is not considered obsolete, but the
+ preferred name `buffer-disable-undo' is new as of Emacs versions
+ 19.
+
+ As editing continues, undo lists get longer and longer. To prevent
+them from using up all available memory space, garbage collection trims
+them back to size limits you can set. (For this purpose, the "size" of
+an undo list measures the cons cells that make up the list, plus the
+strings of deleted text.) Two variables control the range of acceptable
+sizes: `undo-limit' and `undo-strong-limit'.
+
+ - Variable: undo-limit
+ This is the soft limit for the acceptable size of an undo list.
+ The change group at which this size is exceeded is the last one
+ kept.
+
+ - Variable: undo-strong-limit
+ This is the upper limit for the acceptable size of an undo list.
+ The change group at which this size is exceeded is discarded
+ itself (along with all older change groups). There is one
+ exception: the very latest change group is never discarded no
+ matter how big it is.
+
+\1f
+File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
+
+Filling
+=======
+
+ "Filling" means adjusting the lengths of lines (by moving the line
+breaks) so that they are nearly (but no greater than) a specified
+maximum width. Additionally, lines can be "justified", which means
+inserting spaces to make the left and/or right margins line up
+precisely. The width is controlled by the variable `fill-column'. For
+ease of reading, lines should be no longer than 70 or so columns.
+
+ You can use Auto Fill mode (*note Auto Filling::) to fill text
+automatically as you insert it, but changes to existing text may leave
+it improperly filled. Then you must fill the text explicitly.
+
+ Most of the commands in this section return values that are not
+meaningful. All the functions that do filling take note of the current
+left margin, current right margin, and current justification style
+(*note Margins::). If the current justification style is `none', the
+filling functions don't actually do anything.
+
+ Several of the filling functions have an argument JUSTIFY. If it is
+non-`nil', that requests some kind of justification. It can be `left',
+`right', `full', or `center', to request a specific style of
+justification. If it is `t', that means to use the current
+justification style for this part of the text (see
+`current-justification', below).
+
+ When you call the filling functions interactively, using a prefix
+argument implies the value `full' for JUSTIFY.
+
+ - Command: fill-paragraph justify
+ This command fills the paragraph at or after point. If JUSTIFY is
+ non-`nil', each line is justified as well. It uses the ordinary
+ paragraph motion commands to find paragraph boundaries. *Note
+ Paragraphs: (xemacs)Paragraphs.
+
+ - Command: fill-region start end &optional justify
+ This command fills each of the paragraphs in the region from START
+ to END. It justifies as well if JUSTIFY is non-`nil'.
+
+ The variable `paragraph-separate' controls how to distinguish
+ paragraphs. *Note Standard Regexps::.
+
+ - Command: fill-individual-paragraphs start end &optional justify
+ mail-flag
+ This command fills each paragraph in the region according to its
+ individual fill prefix. Thus, if the lines of a paragraph were
+ indented with spaces, the filled paragraph will remain indented in
+ the same fashion.
+
+ The first two arguments, START and END, are the beginning and end
+ of the region to be filled. The third and fourth arguments,
+ JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
+ paragraphs are justified as well as filled. If MAIL-FLAG is
+ non-`nil', it means the function is operating on a mail message
+ and therefore should not fill the header lines.
+
+ Ordinarily, `fill-individual-paragraphs' regards each change in
+ indentation as starting a new paragraph. If
+ `fill-individual-varying-indent' is non-`nil', then only separator
+ lines separate paragraphs. That mode can handle indented
+ paragraphs with additional indentation on the first line.
+
+ - User Option: fill-individual-varying-indent
+ This variable alters the action of `fill-individual-paragraphs' as
+ described above.
+
+ - Command: fill-region-as-paragraph start end &optional justify
+ This command considers a region of text as a paragraph and fills
+ it. If the region was made up of many paragraphs, the blank lines
+ between paragraphs are removed. This function justifies as well
+ as filling when JUSTIFY is non-`nil'.
+
+ In an interactive call, any prefix argument requests justification.
+
+ In Adaptive Fill mode, which is enabled by default,
+ `fill-region-as-paragraph' on an indented paragraph when there is
+ no fill prefix uses the indentation of the second line of the
+ paragraph as the fill prefix.
+
+ - Command: justify-current-line how eop nosqueeze
+ This command inserts spaces between the words of the current line
+ so that the line ends exactly at `fill-column'. It returns `nil'.
+
+ The argument HOW, if non-`nil' specifies explicitly the style of
+ justification. It can be `left', `right', `full', `center', or
+ `none'. If it is `t', that means to do follow specified
+ justification style (see `current-justification', below). `nil'
+ means to do full justification.
+
+ If EOP is non-`nil', that means do left-justification when
+ `current-justification' specifies full justification. This is used
+ for the last line of a paragraph; even if the paragraph as a whole
+ is fully justified, the last line should not be.
+
+ If NOSQUEEZE is non-`nil', that means do not change interior
+ whitespace.
+
+ - User Option: default-justification
+ This variable's value specifies the style of justification to use
+ for text that doesn't specify a style with a text property. The
+ possible values are `left', `right', `full', `center', or `none'.
+ The default value is `left'.
+
+ - Function: current-justification
+ This function returns the proper justification style to use for
+ filling the text around point.
+
+ - Variable: fill-paragraph-function
+ This variable provides a way for major modes to override the
+ filling of paragraphs. If the value is non-`nil',
+ `fill-paragraph' calls this function to do the work. If the
+ function returns a non-`nil' value, `fill-paragraph' assumes the
+ job is done, and immediately returns that value.
+
+ The usual use of this feature is to fill comments in programming
+ language modes. If the function needs to fill a paragraph in the
+ usual way, it can do so as follows:
+
+ (let ((fill-paragraph-function nil))
+ (fill-paragraph arg))
+
+ - Variable: use-hard-newlines
+ If this variable is non-`nil', the filling functions do not delete
+ newlines that have the `hard' text property. These "hard
+ newlines" act as paragraph separators.
+
+\1f
+File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
+
+Margins for Filling
+===================
+
+ - User Option: fill-prefix
+ This variable specifies a string of text that appears at the
+ beginning of normal text lines and should be disregarded when
+ filling them. Any line that fails to start with the fill prefix
+ is considered the start of a paragraph; so is any line that starts
+ with the fill prefix followed by additional whitespace. Lines
+ that start with the fill prefix but no additional whitespace are
+ ordinary text lines that can be filled together. The resulting
+ filled lines also start with the fill prefix.
+
+ The fill prefix follows the left margin whitespace, if any.
+
+ - User Option: fill-column
+ This buffer-local variable specifies the maximum width of filled
+ lines. Its value should be an integer, which is a number of
+ columns. All the filling, justification and centering commands
+ are affected by this variable, including Auto Fill mode (*note
+ Auto Filling::).
+
+ As a practical matter, if you are writing text for other people to
+ read, you should set `fill-column' to no more than 70. Otherwise
+ the line will be too long for people to read comfortably, and this
+ can make the text seem clumsy.
+
+ - Variable: default-fill-column
+ The value of this variable is the default value for `fill-column'
+ in buffers that do not override it. This is the same as
+ `(default-value 'fill-column)'.
+
+ The default value for `default-fill-column' is 70.
+
+ - Command: set-left-margin from to margin
+ This sets the `left-margin' property on the text from FROM to TO
+ to the value MARGIN. If Auto Fill mode is enabled, this command
+ also refills the region to fit the new margin.
+
+ - Command: set-right-margin from to margin
+ This sets the `right-margin' property on the text from FROM to TO
+ to the value MARGIN. If Auto Fill mode is enabled, this command
+ also refills the region to fit the new margin.
+
+ - Function: current-left-margin
+ This function returns the proper left margin value to use for
+ filling the text around point. The value is the sum of the
+ `left-margin' property of the character at the start of the
+ current line (or zero if none), and the value of the variable
+ `left-margin'.
+
+ - Function: current-fill-column
+ This function returns the proper fill column value to use for
+ filling the text around point. The value is the value of the
+ `fill-column' variable, minus the value of the `right-margin'
+ property of the character after point.
+
+ - Command: move-to-left-margin &optional n force
+ This function moves point to the left margin of the current line.
+ The column moved to is determined by calling the function
+ `current-left-margin'. If the argument N is non-`nil',
+ `move-to-left-margin' moves forward N-1 lines first.
+
+ If FORCE is non-`nil', that says to fix the line's indentation if
+ that doesn't match the left margin value.
+
+ - Function: delete-to-left-margin from to
+ This function removes left margin indentation from the text
+ between FROM and TO. The amount of indentation to delete is
+ determined by calling `current-left-margin'. In no case does this
+ function delete non-whitespace.
+
+ - Function: indent-to-left-margin
+ This is the default `indent-line-function', used in Fundamental
+ mode, Text mode, etc. Its effect is to adjust the indentation at
+ the beginning of the current line to the value specified by the
+ variable `left-margin'. This may involve either inserting or
+ deleting whitespace.
+
+ - Variable: left-margin
+ This variable specifies the base left margin column. In
+ Fundamental mode, <LFD> indents to this column. This variable
+ automatically becomes buffer-local when set in any fashion.
+
+\1f
+File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
+
+Auto Filling
+============
+
+ Auto Fill mode is a minor mode that fills lines automatically as text
+is inserted. This section describes the hook used by Auto Fill mode.
+For a description of functions that you can call explicitly to fill and
+justify existing text, see *Note Filling::.
+
+ Auto Fill mode also enables the functions that change the margins and
+justification style to refill portions of the text. *Note Margins::.
+
+ - Variable: auto-fill-function
+ The value of this variable should be a function (of no arguments)
+ to be called after self-inserting a space or a newline. It may be
+ `nil', in which case nothing special is done in that case.
+
+ The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
+ mode is enabled. That is a function whose sole purpose is to
+ implement the usual strategy for breaking a line.
+
+ In older Emacs versions, this variable was named
+ `auto-fill-hook', but since it is not called with the
+ standard convention for hooks, it was renamed to
+ `auto-fill-function' in version 19.
+
+\1f
File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text
Sorting Text
* Saving Properties:: Saving text properties in files, and reading
them back.
-\1f
-File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
-
-Examining Text Properties
--------------------------
-
- The simplest way to examine text properties is to ask for the value
-of a particular property of a particular character. For that, use
-`get-text-property'. Use `text-properties-at' to get the entire
-property list of a character. *Note Property Search::, for functions
-to examine the properties of a number of characters at once.
-
- These functions handle both strings and buffers. (Keep in mind that
-positions in a string start from 0, whereas positions in a buffer start
-from 1.)
-
- - Function: get-text-property pos prop &optional object
- This function returns the value of the PROP property of the
- character after position POS in OBJECT (a buffer or string). The
- argument OBJECT is optional and defaults to the current buffer.
-
- - Function: get-char-property pos prop &optional object
- This function is like `get-text-property', except that it checks
- all extents, not just text-property extents.
-
-
- - Function: text-properties-at position &optional object
- This function returns the entire property list of the character at
- POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
- defaults to the current buffer.
-
- - Variable: default-text-properties
- This variable holds a property list giving default values for text
- properties. Whenever a character does not specify a value for a
- property, the value stored in this list is used instead. Here is
- an example:
-
- (setq default-text-properties '(foo 69))
- ;; Make sure character 1 has no properties of its own.
- (set-text-properties 1 2 nil)
- ;; What we get, when we ask, is the default value.
- (get-text-property 1 'foo)
- => 69
-
-\1f
-File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
-
-Changing Text Properties
-------------------------
-
- The primitives for changing properties apply to a specified range of
-text. The function `set-text-properties' (see end of section) sets the
-entire property list of the text in that range; more often, it is
-useful to add, change, or delete just certain properties specified by
-name.
-
- Since text properties are considered part of the buffer's contents,
-and can affect how the buffer looks on the screen, any change in the
-text properties is considered a buffer modification. Buffer text
-property changes are undoable (*note Undo::).
-
- - Function: put-text-property start end prop value &optional object
- This function sets the PROP property to VALUE for the text between
- START and END in the string or buffer OBJECT. If OBJECT is `nil',
- it defaults to the current buffer.
-
- - Function: add-text-properties start end props &optional object
- This function modifies the text properties for the text between
- START and END in the string or buffer OBJECT. If OBJECT is `nil',
- it defaults to the current buffer.
-
- The argument PROPS specifies which properties to change. It
- should have the form of a property list (*note Property Lists::):
- a list whose elements include the property names followed
- alternately by the corresponding values.
-
- The return value is `t' if the function actually changed some
- property's value; `nil' otherwise (if PROPS is `nil' or its values
- agree with those in the text).
-
- For example, here is how to set the `comment' and `face'
- properties of a range of text:
-
- (add-text-properties START END
- '(comment t face highlight))
-
- - Function: remove-text-properties start end props &optional object
- This function deletes specified text properties from the text
- between START and END in the string or buffer OBJECT. If OBJECT
- is `nil', it defaults to the current buffer.
-
- The argument PROPS specifies which properties to delete. It
- should have the form of a property list (*note Property Lists::):
- a list whose elements are property names alternating with
- corresponding values. But only the names matter--the values that
- accompany them are ignored. For example, here's how to remove the
- `face' property.
-
- (remove-text-properties START END '(face nil))
-
- The return value is `t' if the function actually changed some
- property's value; `nil' otherwise (if PROPS is `nil' or if no
- character in the specified text had any of those properties).
-
- - Function: set-text-properties start end props &optional object
- This function completely replaces the text property list for the
- text between START and END in the string or buffer OBJECT. If
- OBJECT is `nil', it defaults to the current buffer.
-
- The argument PROPS is the new property list. It should be a list
- whose elements are property names alternating with corresponding
- values.
-
- After `set-text-properties' returns, all the characters in the
- specified range have identical properties.
-
- If PROPS is `nil', the effect is to get rid of all properties from
- the specified range of text. Here's an example:
-
- (set-text-properties START END nil)
-
- See also the function `buffer-substring-without-properties' (*note
-Buffer Contents::) which copies text from the buffer but does not copy
-its properties.
-
-\1f
-File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
-
-Property Search Functions
--------------------------
-
- In typical use of text properties, most of the time several or many
-consecutive characters have the same value for a property. Rather than
-writing your programs to examine characters one by one, it is much
-faster to process chunks of text that have the same property value.
-
- Here are functions you can use to do this. They use `eq' for
-comparing property values. In all cases, OBJECT defaults to the
-current buffer.
-
- For high performance, it's very important to use the LIMIT argument
-to these functions, especially the ones that search for a single
-property--otherwise, they may spend a long time scanning to the end of
-the buffer, if the property you are interested in does not change.
-
- Remember that a position is always between two characters; the
-position returned by these functions is between two characters with
-different properties.
-
- - Function: next-property-change pos &optional object limit
- The function scans the text forward from position POS in the
- string or buffer OBJECT till it finds a change in some text
- property, then returns the position of the change. In other
- words, it returns the position of the first character beyond POS
- whose properties are not identical to those of the character just
- after POS.
-
- If LIMIT is non-`nil', then the scan ends at position LIMIT. If
- there is no property change before that point,
- `next-property-change' returns LIMIT.
-
- The value is `nil' if the properties remain unchanged all the way
- to the end of OBJECT and LIMIT is `nil'. If the value is
- non-`nil', it is a position greater than or equal to POS. The
- value equals POS only when LIMIT equals POS.
-
- Here is an example of how to scan the buffer by chunks of text
- within which all properties are constant:
-
- (while (not (eobp))
- (let ((plist (text-properties-at (point)))
- (next-change
- (or (next-property-change (point) (current-buffer))
- (point-max))))
- Process text from point to NEXT-CHANGE...
- (goto-char next-change)))
-
- - Function: next-single-property-change pos prop &optional object limit
- The function scans the text forward from position POS in the
- string or buffer OBJECT till it finds a change in the PROP
- property, then returns the position of the change. In other
- words, it returns the position of the first character beyond POS
- whose PROP property differs from that of the character just after
- POS.
-
- If LIMIT is non-`nil', then the scan ends at position LIMIT. If
- there is no property change before that point,
- `next-single-property-change' returns LIMIT.
-
- The value is `nil' if the property remains unchanged all the way to
- the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
- it is a position greater than or equal to POS; it equals POS only
- if LIMIT equals POS.
-
- - Function: previous-property-change pos &optional object limit
- This is like `next-property-change', but scans back from POS
- instead of forward. If the value is non-`nil', it is a position
- less than or equal to POS; it equals POS only if LIMIT equals POS.
-
- - Function: previous-single-property-change pos prop &optional object
- limit
- This is like `next-single-property-change', but scans back from
- POS instead of forward. If the value is non-`nil', it is a
- position less than or equal to POS; it equals POS only if LIMIT
- equals POS.
-
- - Function: text-property-any start end prop value &optional object
- This function returns non-`nil' if at least one character between
- START and END has a property PROP whose value is VALUE. More
- precisely, it returns the position of the first such character.
- Otherwise, it returns `nil'.
-
- The optional fifth argument, OBJECT, specifies the string or
- buffer to scan. Positions are relative to OBJECT. The default
- for OBJECT is the current buffer.
-
- - Function: text-property-not-all start end prop value &optional object
- This function returns non-`nil' if at least one character between
- START and END has a property PROP whose value differs from VALUE.
- More precisely, it returns the position of the first such
- character. Otherwise, it returns `nil'.
-
- The optional fifth argument, OBJECT, specifies the string or
- buffer to scan. Positions are relative to OBJECT. The default
- for OBJECT is the current buffer.
-
-\1f
-File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
-
-Properties with Special Meanings
---------------------------------
-
- The predefined properties are the same as those for extents. *Note
-Extent Properties::.
-
-\1f
-File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties
-
-Saving Text Properties in Files
--------------------------------
-
- You can save text properties in files, and restore text properties
-when inserting the files, using these two hooks:
-
- - Variable: write-region-annotate-functions
- This variable's value is a list of functions for `write-region' to
- run to encode text properties in some fashion as annotations to
- the text being written in the file. *Note Writing to Files::.
-
- Each function in the list is called with two arguments: the start
- and end of the region to be written. These functions should not
- alter the contents of the buffer. Instead, they should return
- lists indicating annotations to write in the file in addition to
- the text in the buffer.
-
- Each function should return a list of elements of the form
- `(POSITION . STRING)', where POSITION is an integer specifying the
- relative position in the text to be written, and STRING is the
- annotation to add there.
-
- Each list returned by one of these functions must be already
- sorted in increasing order by POSITION. If there is more than one
- function, `write-region' merges the lists destructively into one
- sorted list.
-
- When `write-region' actually writes the text from the buffer to the
- file, it intermixes the specified annotations at the corresponding
- positions. All this takes place without modifying the buffer.
-
- - Variable: after-insert-file-functions
- This variable holds a list of functions for `insert-file-contents'
- to call after inserting a file's contents. These functions should
- scan the inserted text for annotations, and convert them to the
- text properties they stand for.
-
- Each function receives one argument, the length of the inserted
- text; point indicates the start of that text. The function should
- scan that text for annotations, delete them, and create the text
- properties that the annotations specify. The function should
- return the updated length of the inserted text, as it stands after
- those changes. The value returned by one function becomes the
- argument to the next function.
-
- These functions should always return with point at the beginning of
- the inserted text.
-
- The intended use of `after-insert-file-functions' is for converting
- some sort of textual annotations into actual text properties. But
- other uses may be possible.
-
- We invite users to write Lisp programs to store and retrieve text
-properties in files, using these hooks, and thus to experiment with
-various data formats and find good ones. Eventually we hope users will
-produce good, general extensions we can install in Emacs.
-
- We suggest not trying to handle arbitrary Lisp objects as property
-names or property values--because a program that general is probably
-difficult to write, and slow. Instead, choose a set of possible data
-types that are reasonably flexible, and not too hard to encode.
-
- *Note Format Conversion::, for a related feature.
-
-\1f
-File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
-
-Substituting for a Character Code
-=================================
-
- The following functions replace characters within a specified region
-based on their character codes.
-
- - Function: subst-char-in-region start end old-char new-char &optional
- noundo
- This function replaces all occurrences of the character OLD-CHAR
- with the character NEW-CHAR in the region of the current buffer
- defined by START and END.
-
- If NOUNDO is non-`nil', then `subst-char-in-region' does not
- record the change for undo and does not mark the buffer as
- modified. This feature is used for controlling selective display
- (*note Selective Display::).
-
- `subst-char-in-region' does not move point and returns `nil'.
-
- ---------- Buffer: foo ----------
- This is the contents of the buffer before.
- ---------- Buffer: foo ----------
-
- (subst-char-in-region 1 20 ?i ?X)
- => nil
-
- ---------- Buffer: foo ----------
- ThXs Xs the contents of the buffer before.
- ---------- Buffer: foo ----------
-
- - Function: translate-region start end table
- This function applies a translation table to the characters in the
- buffer between positions START and END. The translation table
- TABLE can be either a string, a vector, or a char-table.
-
- If TABLE is a string, its Nth element is the mapping for the
- character with code N.
-
- If TABLE is a vector, its Nth element is the mapping for character
- with code N. Legal mappings are characters, strings, or `nil'
- (meaning don't replace.)
-
- If TABLE is a char-table, its elements describe the mapping
- between characters and their replacements. The char-table should
- be of type `char' or `generic'.
-
- When the TABLE is a string or vector and its length is less than
- the total number of characters (256 without Mule), any characters
- with codes larger than the length of TABLE are not altered by the
- translation.
-
- The return value of `translate-region' is the number of characters
- that were actually changed by the translation. This does not
- count characters that were mapped into themselves in the
- translation table.
-
- *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
- to be a string. This is still the case in FSF Emacs.
-
- The following example creates a char-table that is passed to
- `translate-region', which translates character `a' to `the letter
- a', removes character `b', and translates character `c' to newline.
-
- ---------- Buffer: foo ----------
- Here is a sentence in the buffer.
- ---------- Buffer: foo ----------
-
- (let ((table (make-char-table 'generic)))
- (put-char-table ?a "the letter a" table)
- (put-char-table ?b "" table)
- (put-char-table ?c ?\n table)
- (translate-region (point-min) (point-max) table))
- => 3
-
- ---------- Buffer: foo ----------
- Here is the letter a senten
- e in the uffer.
- ---------- Buffer: foo ----------
-
-\1f
-File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text
-
-Registers
-=========
-
- A register is a sort of variable used in XEmacs editing that can
-hold a marker, a string, a rectangle, a window configuration (of one
-frame), or a frame configuration (of all frames). Each register is
-named by a single character. All characters, including control and
-meta characters (but with the exception of `C-g'), can be used to name
-registers. Thus, there are 255 possible registers. A register is
-designated in Emacs Lisp by a character that is its name.
-
- The functions in this section return unpredictable values unless
-otherwise stated.
-
- - Variable: register-alist
- This variable is an alist of elements of the form `(NAME .
- CONTENTS)'. Normally, there is one element for each XEmacs
- register that has been used.
-
- The object NAME is a character (an integer) identifying the
- register. The object CONTENTS is a string, marker, or list
- representing the register contents. A string represents text
- stored in the register. A marker represents a position. A list
- represents a rectangle; its elements are strings, one per line of
- the rectangle.
-
- - Function: get-register reg
- This function returns the contents of the register REG, or `nil'
- if it has no contents.
-
- - Function: set-register reg value
- This function sets the contents of register REG to VALUE. A
- register can be set to any value, but the other register functions
- expect only certain data types. The return value is VALUE.
-
- - Command: view-register reg
- This command displays what is contained in register REG.
-
- - Command: insert-register reg &optional beforep
- This command inserts contents of register REG into the current
- buffer.
-
- Normally, this command puts point before the inserted text, and the
- mark after it. However, if the optional second argument BEFOREP
- is non-`nil', it puts the mark before and point after. You can
- pass a non-`nil' second argument BEFOREP to this function
- interactively by supplying any prefix argument.
-
- If the register contains a rectangle, then the rectangle is
- inserted with its upper left corner at point. This means that
- text is inserted in the current line and underneath it on
- successive lines.
-
- If the register contains something other than saved text (a
- string) or a rectangle (a list), currently useless things happen.
- This may be changed in the future.
-
-\1f
-File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
-
-Transposition of Text
-=====================
-
- This subroutine is used by the transposition commands.
-
- - Function: transpose-regions start1 end1 start2 end2 &optional
- leave-markers
- This function exchanges two nonoverlapping portions of the buffer.
- Arguments START1 and END1 specify the bounds of one portion and
- arguments START2 and END2 specify the bounds of the other portion.
-
- Normally, `transpose-regions' relocates markers with the transposed
- text; a marker previously positioned within one of the two
- transposed portions moves along with that portion, thus remaining
- between the same two characters in their new position. However,
- if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
- this--it leaves all markers unrelocated.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
+
+Examining Text Properties
+-------------------------
+
+ The simplest way to examine text properties is to ask for the value
+of a particular property of a particular character. For that, use
+`get-text-property'. Use `text-properties-at' to get the entire
+property list of a character. *Note Property Search::, for functions
+to examine the properties of a number of characters at once.
+
+ These functions handle both strings and buffers. (Keep in mind that
+positions in a string start from 0, whereas positions in a buffer start
+from 1.)
+
+ - Function: get-text-property pos prop &optional object
+ This function returns the value of the PROP property of the
+ character after position POS in OBJECT (a buffer or string). The
+ argument OBJECT is optional and defaults to the current buffer.
+
+ - Function: get-char-property pos prop &optional object
+ This function is like `get-text-property', except that it checks
+ all extents, not just text-property extents.
+
+
+ - Function: text-properties-at position &optional object
+ This function returns the entire property list of the character at
+ POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
+ defaults to the current buffer.
+
+ - Variable: default-text-properties
+ This variable holds a property list giving default values for text
+ properties. Whenever a character does not specify a value for a
+ property, the value stored in this list is used instead. Here is
+ an example:
+
+ (setq default-text-properties '(foo 69))
+ ;; Make sure character 1 has no properties of its own.
+ (set-text-properties 1 2 nil)
+ ;; What we get, when we ask, is the default value.
+ (get-text-property 1 'foo)
+ => 69
+
+\1f
+File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
+
+Changing Text Properties
+------------------------
+
+ The primitives for changing properties apply to a specified range of
+text. The function `set-text-properties' (see end of section) sets the
+entire property list of the text in that range; more often, it is
+useful to add, change, or delete just certain properties specified by
+name.
+
+ Since text properties are considered part of the buffer's contents,
+and can affect how the buffer looks on the screen, any change in the
+text properties is considered a buffer modification. Buffer text
+property changes are undoable (*note Undo::).
+
+ - Function: put-text-property start end prop value &optional object
+ This function sets the PROP property to VALUE for the text between
+ START and END in the string or buffer OBJECT. If OBJECT is `nil',
+ it defaults to the current buffer.
+
+ - Function: add-text-properties start end props &optional object
+ This function modifies the text properties for the text between
+ START and END in the string or buffer OBJECT. If OBJECT is `nil',
+ it defaults to the current buffer.
+
+ The argument PROPS specifies which properties to change. It
+ should have the form of a property list (*note Property Lists::):
+ a list whose elements include the property names followed
+ alternately by the corresponding values.
+
+ The return value is `t' if the function actually changed some
+ property's value; `nil' otherwise (if PROPS is `nil' or its values
+ agree with those in the text).
+
+ For example, here is how to set the `comment' and `face'
+ properties of a range of text:
+
+ (add-text-properties START END
+ '(comment t face highlight))
+
+ - Function: remove-text-properties start end props &optional object
+ This function deletes specified text properties from the text
+ between START and END in the string or buffer OBJECT. If OBJECT
+ is `nil', it defaults to the current buffer.
+
+ The argument PROPS specifies which properties to delete. It
+ should have the form of a property list (*note Property Lists::):
+ a list whose elements are property names alternating with
+ corresponding values. But only the names matter--the values that
+ accompany them are ignored. For example, here's how to remove the
+ `face' property.
+
+ (remove-text-properties START END '(face nil))
+
+ The return value is `t' if the function actually changed some
+ property's value; `nil' otherwise (if PROPS is `nil' or if no
+ character in the specified text had any of those properties).
+
+ - Function: set-text-properties start end props &optional object
+ This function completely replaces the text property list for the
+ text between START and END in the string or buffer OBJECT. If
+ OBJECT is `nil', it defaults to the current buffer.
+
+ The argument PROPS is the new property list. It should be a list
+ whose elements are property names alternating with corresponding
+ values.
+
+ After `set-text-properties' returns, all the characters in the
+ specified range have identical properties.
+
+ If PROPS is `nil', the effect is to get rid of all properties from
+ the specified range of text. Here's an example:
+
+ (set-text-properties START END nil)
+
+ See also the function `buffer-substring-without-properties' (*note
+Buffer Contents::) which copies text from the buffer but does not copy
+its properties.
+
+\1f
+File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
+
+Property Search Functions
+-------------------------
+
+ In typical use of text properties, most of the time several or many
+consecutive characters have the same value for a property. Rather than
+writing your programs to examine characters one by one, it is much
+faster to process chunks of text that have the same property value.
+
+ Here are functions you can use to do this. They use `eq' for
+comparing property values. In all cases, OBJECT defaults to the
+current buffer.
+
+ For high performance, it's very important to use the LIMIT argument
+to these functions, especially the ones that search for a single
+property--otherwise, they may spend a long time scanning to the end of
+the buffer, if the property you are interested in does not change.
+
+ Remember that a position is always between two characters; the
+position returned by these functions is between two characters with
+different properties.
+
+ - Function: next-property-change pos &optional object limit
+ The function scans the text forward from position POS in the
+ string or buffer OBJECT till it finds a change in some text
+ property, then returns the position of the change. In other
+ words, it returns the position of the first character beyond POS
+ whose properties are not identical to those of the character just
+ after POS.
+
+ If LIMIT is non-`nil', then the scan ends at position LIMIT. If
+ there is no property change before that point,
+ `next-property-change' returns LIMIT.
+
+ The value is `nil' if the properties remain unchanged all the way
+ to the end of OBJECT and LIMIT is `nil'. If the value is
+ non-`nil', it is a position greater than or equal to POS. The
+ value equals POS only when LIMIT equals POS.
+
+ Here is an example of how to scan the buffer by chunks of text
+ within which all properties are constant:
+
+ (while (not (eobp))
+ (let ((plist (text-properties-at (point)))
+ (next-change
+ (or (next-property-change (point) (current-buffer))
+ (point-max))))
+ Process text from point to NEXT-CHANGE...
+ (goto-char next-change)))
+
+ - Function: next-single-property-change pos prop &optional object limit
+ The function scans the text forward from position POS in the
+ string or buffer OBJECT till it finds a change in the PROP
+ property, then returns the position of the change. In other
+ words, it returns the position of the first character beyond POS
+ whose PROP property differs from that of the character just after
+ POS.
+
+ If LIMIT is non-`nil', then the scan ends at position LIMIT. If
+ there is no property change before that point,
+ `next-single-property-change' returns LIMIT.
+
+ The value is `nil' if the property remains unchanged all the way to
+ the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
+ it is a position greater than or equal to POS; it equals POS only
+ if LIMIT equals POS.
+
+ - Function: previous-property-change pos &optional object limit
+ This is like `next-property-change', but scans back from POS
+ instead of forward. If the value is non-`nil', it is a position
+ less than or equal to POS; it equals POS only if LIMIT equals POS.
+
+ - Function: previous-single-property-change pos prop &optional object
+ limit
+ This is like `next-single-property-change', but scans back from
+ POS instead of forward. If the value is non-`nil', it is a
+ position less than or equal to POS; it equals POS only if LIMIT
+ equals POS.
+
+ - Function: text-property-any start end prop value &optional object
+ This function returns non-`nil' if at least one character between
+ START and END has a property PROP whose value is VALUE. More
+ precisely, it returns the position of the first such character.
+ Otherwise, it returns `nil'.
+
+ The optional fifth argument, OBJECT, specifies the string or
+ buffer to scan. Positions are relative to OBJECT. The default
+ for OBJECT is the current buffer.
+
+ - Function: text-property-not-all start end prop value &optional object
+ This function returns non-`nil' if at least one character between
+ START and END has a property PROP whose value differs from VALUE.
+ More precisely, it returns the position of the first such
+ character. Otherwise, it returns `nil'.
+
+ The optional fifth argument, OBJECT, specifies the string or
+ buffer to scan. Positions are relative to OBJECT. The default
+ for OBJECT is the current buffer.
+
+\1f
+File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
+
+Properties with Special Meanings
+--------------------------------
+
+ The predefined properties are the same as those for extents. *Note
+Extent Properties::.
+
+\1f
+File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties
+
+Saving Text Properties in Files
+-------------------------------
+
+ You can save text properties in files, and restore text properties
+when inserting the files, using these two hooks:
+
+ - Variable: write-region-annotate-functions
+ This variable's value is a list of functions for `write-region' to
+ run to encode text properties in some fashion as annotations to
+ the text being written in the file. *Note Writing to Files::.
+
+ Each function in the list is called with two arguments: the start
+ and end of the region to be written. These functions should not
+ alter the contents of the buffer. Instead, they should return
+ lists indicating annotations to write in the file in addition to
+ the text in the buffer.
+
+ Each function should return a list of elements of the form
+ `(POSITION . STRING)', where POSITION is an integer specifying the
+ relative position in the text to be written, and STRING is the
+ annotation to add there.
+
+ Each list returned by one of these functions must be already
+ sorted in increasing order by POSITION. If there is more than one
+ function, `write-region' merges the lists destructively into one
+ sorted list.
+
+ When `write-region' actually writes the text from the buffer to the
+ file, it intermixes the specified annotations at the corresponding
+ positions. All this takes place without modifying the buffer.
+
+ - Variable: after-insert-file-functions
+ This variable holds a list of functions for `insert-file-contents'
+ to call after inserting a file's contents. These functions should
+ scan the inserted text for annotations, and convert them to the
+ text properties they stand for.
+
+ Each function receives one argument, the length of the inserted
+ text; point indicates the start of that text. The function should
+ scan that text for annotations, delete them, and create the text
+ properties that the annotations specify. The function should
+ return the updated length of the inserted text, as it stands after
+ those changes. The value returned by one function becomes the
+ argument to the next function.
+
+ These functions should always return with point at the beginning of
+ the inserted text.
+
+ The intended use of `after-insert-file-functions' is for converting
+ some sort of textual annotations into actual text properties. But
+ other uses may be possible.
+
+ We invite users to write Lisp programs to store and retrieve text
+properties in files, using these hooks, and thus to experiment with
+various data formats and find good ones. Eventually we hope users will
+produce good, general extensions we can install in Emacs.
+
+ We suggest not trying to handle arbitrary Lisp objects as property
+names or property values--because a program that general is probably
+difficult to write, and slow. Instead, choose a set of possible data
+types that are reasonably flexible, and not too hard to encode.
+
+ *Note Format Conversion::, for a related feature.
+
+\1f
+File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
+
+Substituting for a Character Code
+=================================
+
+ The following functions replace characters within a specified region
+based on their character codes.
+
+ - Function: subst-char-in-region start end old-char new-char &optional
+ noundo
+ This function replaces all occurrences of the character OLD-CHAR
+ with the character NEW-CHAR in the region of the current buffer
+ defined by START and END.
+
+ If NOUNDO is non-`nil', then `subst-char-in-region' does not
+ record the change for undo and does not mark the buffer as
+ modified. This feature is used for controlling selective display
+ (*note Selective Display::).
+
+ `subst-char-in-region' does not move point and returns `nil'.
+
+ ---------- Buffer: foo ----------
+ This is the contents of the buffer before.
+ ---------- Buffer: foo ----------
+
+ (subst-char-in-region 1 20 ?i ?X)
+ => nil
+
+ ---------- Buffer: foo ----------
+ ThXs Xs the contents of the buffer before.
+ ---------- Buffer: foo ----------
+
+ - Function: translate-region start end table
+ This function applies a translation table to the characters in the
+ buffer between positions START and END. The translation table
+ TABLE can be either a string, a vector, or a char-table.
+
+ If TABLE is a string, its Nth element is the mapping for the
+ character with code N.
+
+ If TABLE is a vector, its Nth element is the mapping for character
+ with code N. Legal mappings are characters, strings, or `nil'
+ (meaning don't replace.)
+
+ If TABLE is a char-table, its elements describe the mapping
+ between characters and their replacements. The char-table should
+ be of type `char' or `generic'.
+
+ When the TABLE is a string or vector and its length is less than
+ the total number of characters (256 without Mule), any characters
+ with codes larger than the length of TABLE are not altered by the
+ translation.
+
+ The return value of `translate-region' is the number of characters
+ that were actually changed by the translation. This does not
+ count characters that were mapped into themselves in the
+ translation table.
+
+ *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
+ to be a string. This is still the case in FSF Emacs.
+
+ The following example creates a char-table that is passed to
+ `translate-region', which translates character `a' to `the letter
+ a', removes character `b', and translates character `c' to newline.
+
+ ---------- Buffer: foo ----------
+ Here is a sentence in the buffer.
+ ---------- Buffer: foo ----------
+
+ (let ((table (make-char-table 'generic)))
+ (put-char-table ?a "the letter a" table)
+ (put-char-table ?b "" table)
+ (put-char-table ?c ?\n table)
+ (translate-region (point-min) (point-max) table))
+ => 3
+
+ ---------- Buffer: foo ----------
+ Here is the letter a senten
+ e in the uffer.
+ ---------- Buffer: foo ----------
+
+\1f
+File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text
+
+Registers
+=========
+
+ A register is a sort of variable used in XEmacs editing that can
+hold a marker, a string, a rectangle, a window configuration (of one
+frame), or a frame configuration (of all frames). Each register is
+named by a single character. All characters, including control and
+meta characters (but with the exception of `C-g'), can be used to name
+registers. Thus, there are 255 possible registers. A register is
+designated in Emacs Lisp by a character that is its name.
+
+ The functions in this section return unpredictable values unless
+otherwise stated.
+
+ - Variable: register-alist
+ This variable is an alist of elements of the form `(NAME .
+ CONTENTS)'. Normally, there is one element for each XEmacs
+ register that has been used.
+
+ The object NAME is a character (an integer) identifying the
+ register. The object CONTENTS is a string, marker, or list
+ representing the register contents. A string represents text
+ stored in the register. A marker represents a position. A list
+ represents a rectangle; its elements are strings, one per line of
+ the rectangle.
+
+ - Function: get-register reg
+ This function returns the contents of the register REG, or `nil'
+ if it has no contents.
+
+ - Function: set-register reg value
+ This function sets the contents of register REG to VALUE. A
+ register can be set to any value, but the other register functions
+ expect only certain data types. The return value is VALUE.
+
+ - Command: view-register reg
+ This command displays what is contained in register REG.
+
+ - Command: insert-register reg &optional beforep
+ This command inserts contents of register REG into the current
+ buffer.
+
+ Normally, this command puts point before the inserted text, and the
+ mark after it. However, if the optional second argument BEFOREP
+ is non-`nil', it puts the mark before and point after. You can
+ pass a non-`nil' second argument BEFOREP to this function
+ interactively by supplying any prefix argument.
+
+ If the register contains a rectangle, then the rectangle is
+ inserted with its upper left corner at point. This means that
+ text is inserted in the current line and underneath it on
+ successive lines.
+
+ If the register contains something other than saved text (a
+ string) or a rectangle (a list), currently useless things happen.
+ This may be changed in the future.
+
+\1f
+File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
+
+Transposition of Text
+=====================
+
+ This subroutine is used by the transposition commands.
+
+ - Function: transpose-regions start1 end1 start2 end2 &optional
+ leave-markers
+ This function exchanges two nonoverlapping portions of the buffer.
+ Arguments START1 and END1 specify the bounds of one portion and
+ arguments START2 and END2 specify the bounds of the other portion.
+
+ Normally, `transpose-regions' relocates markers with the transposed
+ text; a marker previously positioned within one of the two
+ transposed portions moves along with that portion, thus remaining
+ between the same two characters in their new position. However,
+ if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
+ this--it leaves all markers unrelocated.
+
+\1f
File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text
Change Hooks
(re-search-forward
(concat "\\s-" (regexp-quote string) "\\s-"))
-\1f
-File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
-
-Complex Regexp Example
-----------------------
-
- Here is a complicated regexp, used by XEmacs to recognize the end of
-a sentence together with any whitespace that follows. It is the value
-of the variable `sentence-end'.
-
- First, we show the regexp as a string in Lisp syntax to distinguish
-spaces from tab characters. The string constant begins and ends with a
-double-quote. `\"' stands for a double-quote as part of the string,
-`\\' for a backslash as part of the string, `\t' for a tab and `\n' for
-a newline.
-
- "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
-
- In contrast, if you evaluate the variable `sentence-end', you will
-see the following:
-
- sentence-end
- =>
- "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[
- ]*"
-
-In this output, tab and newline appear as themselves.
-
- This regular expression contains four parts in succession and can be
-deciphered as follows:
-
-`[.?!]'
- The first part of the pattern is a character set that matches any
- one of three characters: period, question mark, and exclamation
- mark. The match must begin with one of these three characters.
-
-`[]\"')}]*'
- The second part of the pattern matches any closing braces and
- quotation marks, zero or more of them, that may follow the period,
- question mark or exclamation mark. The `\"' is Lisp syntax for a
- double-quote in a string. The `*' at the end indicates that the
- immediately preceding regular expression (a character set, in this
- case) may be repeated zero or more times.
-
-`\\($\\| $\\|\t\\| \\)'
- The third part of the pattern matches the whitespace that follows
- the end of a sentence: the end of a line, or a tab, or two spaces.
- The double backslashes mark the parentheses and vertical bars as
- regular expression syntax; the parentheses delimit a group and the
- vertical bars separate alternatives. The dollar sign is used to
- match the end of a line.
-
-`[ \t\n]*'
- Finally, the last part of the pattern matches any additional
- whitespace beyond the minimum needed to end a sentence.
-
-\1f
-File: lispref.info, Node: Regexp Search, Next: POSIX Regexps, Prev: Regular Expressions, Up: Searching and Matching
-
-Regular Expression Searching
-============================
-
- In XEmacs, you can search for the next match for a regexp either
-incrementally or not. Incremental search commands are described in the
-`The XEmacs Reference Manual'. *Note Regular Expression Search:
-(emacs)Regexp Search. Here we describe only the search functions
-useful in programs. The principal one is `re-search-forward'.
-
- - Command: re-search-forward regexp &optional limit noerror repeat
- This function searches forward in the current buffer for a string
- of text that is matched by the regular expression REGEXP. The
- function skips over any amount of text that is not matched by
- REGEXP, and leaves point at the end of the first match found. It
- returns the new value of point.
-
- If LIMIT is non-`nil' (it must be a position in the current
- buffer), then it is the upper bound to the search. No match
- extending after that position is accepted.
-
- What happens when the search fails depends on the value of
- NOERROR. If NOERROR is `nil', a `search-failed' error is
- signaled. If NOERROR is `t', `re-search-forward' does nothing and
- returns `nil'. If NOERROR is neither `nil' nor `t', then
- `re-search-forward' moves point to LIMIT (or the end of the
- buffer) and returns `nil'.
-
- If REPEAT is supplied (it must be a positive number), then the
- search is repeated that many times (each time starting at the end
- of the previous time's match). If these successive searches
- succeed, the function succeeds, moving point and returning its new
- value. Otherwise the search fails.
-
- In the following example, point is initially before the `T'.
- Evaluating the search call moves point to the end of that line
- (between the `t' of `hat' and the newline).
-
- ---------- Buffer: foo ----------
- I read "-!-The cat in the hat
- comes back" twice.
- ---------- Buffer: foo ----------
-
- (re-search-forward "[a-z]+" nil t 5)
- => 27
-
- ---------- Buffer: foo ----------
- I read "The cat in the hat-!-
- comes back" twice.
- ---------- Buffer: foo ----------
-
- - Command: re-search-backward regexp &optional limit noerror repeat
- This function searches backward in the current buffer for a string
- of text that is matched by the regular expression REGEXP, leaving
- point at the beginning of the first text found.
-
- This function is analogous to `re-search-forward', but they are not
- simple mirror images. `re-search-forward' finds the match whose
- beginning is as close as possible to the starting point. If
- `re-search-backward' were a perfect mirror image, it would find the
- match whose end is as close as possible. However, in fact it
- finds the match whose beginning is as close as possible. The
- reason is that matching a regular expression at a given spot
- always works from beginning to end, and starts at a specified
- beginning position.
-
- A true mirror-image of `re-search-forward' would require a special
- feature for matching regexps from end to beginning. It's not
- worth the trouble of implementing that.
-
- - Function: string-match regexp string &optional start
- This function returns the index of the start of the first match for
- the regular expression REGEXP in STRING, or `nil' if there is no
- match. If START is non-`nil', the search starts at that index in
- STRING.
-
- For example,
-
- (string-match
- "quick" "The quick brown fox jumped quickly.")
- => 4
- (string-match
- "quick" "The quick brown fox jumped quickly." 8)
- => 27
-
- The index of the first character of the string is 0, the index of
- the second character is 1, and so on.
-
- After this function returns, the index of the first character
- beyond the match is available as `(match-end 0)'. *Note Match
- Data::.
-
- (string-match
- "quick" "The quick brown fox jumped quickly." 8)
- => 27
-
- (match-end 0)
- => 32
-
- - Function: split-string string &optional pattern
- This function splits STRING to substrings delimited by PATTERN,
- and returns a list of substrings. If PATTERN is omitted, it
- defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by
- white-space.
-
- (split-string "foo bar")
- => ("foo" "bar")
-
- (split-string "something")
- => ("something")
-
- (split-string "a:b:c" ":")
- => ("a" "b" "c")
-
- (split-string ":a::b:c" ":")
- => ("" "a" "" "b" "c")
-
- - Function: split-path path
- This function splits a search path into a list of strings. The
- path components are separated with the characters specified with
- `path-separator'. Under Unix, `path-separator' will normally be
- `:', while under Windows, it will be `;'.
-
- - Function: looking-at regexp
- This function determines whether the text in the current buffer
- directly following point matches the regular expression REGEXP.
- "Directly following" means precisely that: the search is
- "anchored" and it can succeed only starting with the first
- character following point. The result is `t' if so, `nil'
- otherwise.
-
- This function does not move point, but it updates the match data,
- which you can access using `match-beginning' and `match-end'.
- *Note Match Data::.
-
- In this example, point is located directly before the `T'. If it
- were anywhere else, the result would be `nil'.
-
- ---------- Buffer: foo ----------
- I read "-!-The cat in the hat
- comes back" twice.
- ---------- Buffer: foo ----------
-
- (looking-at "The cat in the hat$")
- => t
-
-\1f
-File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching
-
-POSIX Regular Expression Searching
-==================================
-
- The usual regular expression functions do backtracking when necessary
-to handle the `\|' and repetition constructs, but they continue this
-only until they find _some_ match. Then they succeed and report the
-first match found.
-
- This section describes alternative search functions which perform the
-full backtracking specified by the POSIX standard for regular expression
-matching. They continue backtracking until they have tried all
-possibilities and found all matches, so they can report the longest
-match, as required by POSIX. This is much slower, so use these
-functions only when you really need the longest match.
-
- In Emacs versions prior to 19.29, these functions did not exist, and
-the functions described above implemented full POSIX backtracking.
-
- - Function: posix-search-forward regexp &optional limit noerror repeat
- This is like `re-search-forward' except that it performs the full
- backtracking specified by the POSIX standard for regular expression
- matching.
-
- - Function: posix-search-backward regexp &optional limit noerror repeat
- This is like `re-search-backward' except that it performs the full
- backtracking specified by the POSIX standard for regular expression
- matching.
-
- - Function: posix-looking-at regexp
- This is like `looking-at' except that it performs the full
- backtracking specified by the POSIX standard for regular expression
- matching.
-
- - Function: posix-string-match regexp string &optional start
- This is like `string-match' except that it performs the full
- backtracking specified by the POSIX standard for regular expression
- matching.
-
-\1f
-File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching
-
-Search and Replace
-==================
-
- - Function: perform-replace from-string replacements query-flag
- regexp-flag delimited-flag &optional repeat-count map
- This function is the guts of `query-replace' and related commands.
- It searches for occurrences of FROM-STRING and replaces some or
- all of them. If QUERY-FLAG is `nil', it replaces all occurrences;
- otherwise, it asks the user what to do about each one.
-
- If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a
- regular expression; otherwise, it must match literally. If
- DELIMITED-FLAG is non-`nil', then only replacements surrounded by
- word boundaries are considered.
-
- The argument REPLACEMENTS specifies what to replace occurrences
- with. If it is a string, that string is used. It can also be a
- list of strings, to be used in cyclic order.
-
- If REPEAT-COUNT is non-`nil', it should be an integer. Then it
- specifies how many times to use each of the strings in the
- REPLACEMENTS list before advancing cyclicly to the next one.
-
- Normally, the keymap `query-replace-map' defines the possible user
- responses for queries. The argument MAP, if non-`nil', is a
- keymap to use instead of `query-replace-map'.
-
- - Variable: query-replace-map
- This variable holds a special keymap that defines the valid user
- responses for `query-replace' and related functions, as well as
- `y-or-n-p' and `map-y-or-n-p'. It is unusual in two ways:
-
- * The "key bindings" are not commands, just symbols that are
- meaningful to the functions that use this map.
-
- * Prefix keys are not supported; each key binding must be for a
- single event key sequence. This is because the functions
- don't use read key sequence to get the input; instead, they
- read a single event and look it up "by hand."
-
- Here are the meaningful "bindings" for `query-replace-map'. Several
-of them are meaningful only for `query-replace' and friends.
-
-`act'
- Do take the action being considered--in other words, "yes."
-
-`skip'
- Do not take action for this question--in other words, "no."
-
-`exit'
- Answer this question "no," and give up on the entire series of
- questions, assuming that the answers will be "no."
-
-`act-and-exit'
- Answer this question "yes," and give up on the entire series of
- questions, assuming that subsequent answers will be "no."
-
-`act-and-show'
- Answer this question "yes," but show the results--don't advance yet
- to the next question.
-
-`automatic'
- Answer this question and all subsequent questions in the series
- with "yes," without further user interaction.
-
-`backup'
- Move back to the previous place that a question was asked about.
-
-`edit'
- Enter a recursive edit to deal with this question--instead of any
- other action that would normally be taken.
-
-`delete-and-edit'
- Delete the text being considered, then enter a recursive edit to
- replace it.
-
-`recenter'
- Redisplay and center the window, then ask the same question again.
-
-`quit'
- Perform a quit right away. Only `y-or-n-p' and related functions
- use this answer.
-
-`help'
- Display some help, then ask again.
-
-\1f
-File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching
-
-The Match Data
-==============
-
- XEmacs keeps track of the positions of the start and end of segments
-of text found during a regular expression search. This means, for
-example, that you can search for a complex pattern, such as a date in
-an Rmail message, and then extract parts of the match under control of
-the pattern.
-
- Because the match data normally describe the most recent search only,
-you must be careful not to do another search inadvertently between the
-search you wish to refer back to and the use of the match data. If you
-can't avoid another intervening search, you must save and restore the
-match data around it, to prevent it from being overwritten.
-
-* Menu:
-
-* Simple Match Data:: Accessing single items of match data,
- such as where a particular subexpression started.
-* Replacing Match:: Replacing a substring that was matched.
-* Entire Match Data:: Accessing the entire match data at once, as a list.
-* Saving Match Data:: Saving and restoring the match data.
-
-\1f
-File: lispref.info, Node: Simple Match Data, Next: Replacing Match, Up: Match Data
-
-Simple Match Data Access
-------------------------
-
- This section explains how to use the match data to find out what was
-matched by the last search or match operation.
-
- You can ask about the entire matching text, or about a particular
-parenthetical subexpression of a regular expression. The COUNT
-argument in the functions below specifies which. If COUNT is zero, you
-are asking about the entire match. If COUNT is positive, it specifies
-which subexpression you want.
-
- Recall that the subexpressions of a regular expression are those
-expressions grouped with escaped parentheses, `\(...\)'. The COUNTth
-subexpression is found by counting occurrences of `\(' from the
-beginning of the whole regular expression. The first subexpression is
-numbered 1, the second 2, and so on. Only regular expressions can have
-subexpressions--after a simple string search, the only information
-available is about the entire match.
-
- - Function: match-string count &optional in-string
- This function returns, as a string, the text matched in the last
- search or match operation. It returns the entire text if COUNT is
- zero, or just the portion corresponding to the COUNTth
- parenthetical subexpression, if COUNT is positive. If COUNT is
- out of range, or if that subexpression didn't match anything, the
- value is `nil'.
-
- If the last such operation was done against a string with
- `string-match', then you should pass the same string as the
- argument IN-STRING. Otherwise, after a buffer search or match,
- you should omit IN-STRING or pass `nil' for it; but you should
- make sure that the current buffer when you call `match-string' is
- the one in which you did the searching or matching.
-
- - Function: match-beginning count
- This function returns the position of the start of text matched by
- the last regular expression searched for, or a subexpression of it.
-
- If COUNT is zero, then the value is the position of the start of
- the entire match. Otherwise, COUNT specifies a subexpression in
- the regular expression, and the value of the function is the
- starting position of the match for that subexpression.
-
- The value is `nil' for a subexpression inside a `\|' alternative
- that wasn't used in the match.
-
- - Function: match-end count
- This function is like `match-beginning' except that it returns the
- position of the end of the match, rather than the position of the
- beginning.
-
- Here is an example of using the match data, with a comment showing
-the positions within the text:
-
- (string-match "\\(qu\\)\\(ick\\)"
- "The quick fox jumped quickly.")
- ;0123456789
- => 4
-
- (match-string 0 "The quick fox jumped quickly.")
- => "quick"
- (match-string 1 "The quick fox jumped quickly.")
- => "qu"
- (match-string 2 "The quick fox jumped quickly.")
- => "ick"
-
- (match-beginning 1) ; The beginning of the match
- => 4 ; with `qu' is at index 4.
-
- (match-beginning 2) ; The beginning of the match
- => 6 ; with `ick' is at index 6.
-
- (match-end 1) ; The end of the match
- => 6 ; with `qu' is at index 6.
-
- (match-end 2) ; The end of the match
- => 9 ; with `ick' is at index 9.
-
- Here is another example. Point is initially located at the beginning
-of the line. Searching moves point to between the space and the word
-`in'. The beginning of the entire match is at the 9th character of the
-buffer (`T'), and the beginning of the match for the first
-subexpression is at the 13th character (`c').
-
- (list
- (re-search-forward "The \\(cat \\)")
- (match-beginning 0)
- (match-beginning 1))
- => (9 9 13)
-
- ---------- Buffer: foo ----------
- I read "The cat -!-in the hat comes back" twice.
- ^ ^
- 9 13
- ---------- Buffer: foo ----------
-
-(In this case, the index returned is a buffer position; the first
-character of the buffer counts as 1.)
-
-\1f
-File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data
-
-Replacing the Text That Matched
--------------------------------
-
- This function replaces the text matched by the last search with
-REPLACEMENT.
-
- - Function: replace-match replacement &optional fixedcase literal
- string
- This function replaces the text in the buffer (or in STRING) that
- was matched by the last search. It replaces that text with
- REPLACEMENT.
-
- If you did the last search in a buffer, you should specify `nil'
- for STRING. Then `replace-match' does the replacement by editing
- the buffer; it leaves point at the end of the replacement text,
- and returns `t'.
-
- If you did the search in a string, pass the same string as STRING.
- Then `replace-match' does the replacement by constructing and
- returning a new string.
-
- If FIXEDCASE is non-`nil', then the case of the replacement text
- is not changed; otherwise, the replacement text is converted to a
- different case depending upon the capitalization of the text to be
- replaced. If the original text is all upper case, the replacement
- text is converted to upper case. If the first word of the
- original text is capitalized, then the first word of the
- replacement text is capitalized. If the original text contains
- just one word, and that word is a capital letter, `replace-match'
- considers this a capitalized first word rather than all upper case.
-
- If `case-replace' is `nil', then case conversion is not done,
- regardless of the value of FIXED-CASE. *Note Searching and Case::.
-
- If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
- it is, the only alterations being case changes as needed. If it
- is `nil' (the default), then the character `\' is treated
- specially. If a `\' appears in REPLACEMENT, then it must be part
- of one of the following sequences:
-
- `\&'
- `\&' stands for the entire text being replaced.
-
- `\N'
- `\N', where N is a digit, stands for the text that matched
- the Nth subexpression in the original regexp. Subexpressions
- are those expressions grouped inside `\(...\)'.
-
- `\\'
- `\\' stands for a single `\' in the replacement text.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
+
+Complex Regexp Example
+----------------------
+
+ Here is a complicated regexp, used by XEmacs to recognize the end of
+a sentence together with any whitespace that follows. It is the value
+of the variable `sentence-end'.
+
+ First, we show the regexp as a string in Lisp syntax to distinguish
+spaces from tab characters. The string constant begins and ends with a
+double-quote. `\"' stands for a double-quote as part of the string,
+`\\' for a backslash as part of the string, `\t' for a tab and `\n' for
+a newline.
+
+ "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
+
+ In contrast, if you evaluate the variable `sentence-end', you will
+see the following:
+
+ sentence-end
+ =>
+ "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[
+ ]*"
+
+In this output, tab and newline appear as themselves.
+
+ This regular expression contains four parts in succession and can be
+deciphered as follows:
+
+`[.?!]'
+ The first part of the pattern is a character set that matches any
+ one of three characters: period, question mark, and exclamation
+ mark. The match must begin with one of these three characters.
+
+`[]\"')}]*'
+ The second part of the pattern matches any closing braces and
+ quotation marks, zero or more of them, that may follow the period,
+ question mark or exclamation mark. The `\"' is Lisp syntax for a
+ double-quote in a string. The `*' at the end indicates that the
+ immediately preceding regular expression (a character set, in this
+ case) may be repeated zero or more times.
+
+`\\($\\| $\\|\t\\| \\)'
+ The third part of the pattern matches the whitespace that follows
+ the end of a sentence: the end of a line, or a tab, or two spaces.
+ The double backslashes mark the parentheses and vertical bars as
+ regular expression syntax; the parentheses delimit a group and the
+ vertical bars separate alternatives. The dollar sign is used to
+ match the end of a line.
+
+`[ \t\n]*'
+ Finally, the last part of the pattern matches any additional
+ whitespace beyond the minimum needed to end a sentence.
+
+\1f
+File: lispref.info, Node: Regexp Search, Next: POSIX Regexps, Prev: Regular Expressions, Up: Searching and Matching
+
+Regular Expression Searching
+============================
+
+ In XEmacs, you can search for the next match for a regexp either
+incrementally or not. Incremental search commands are described in the
+`The XEmacs Reference Manual'. *Note Regular Expression Search:
+(emacs)Regexp Search. Here we describe only the search functions
+useful in programs. The principal one is `re-search-forward'.
+
+ - Command: re-search-forward regexp &optional limit noerror repeat
+ This function searches forward in the current buffer for a string
+ of text that is matched by the regular expression REGEXP. The
+ function skips over any amount of text that is not matched by
+ REGEXP, and leaves point at the end of the first match found. It
+ returns the new value of point.
+
+ If LIMIT is non-`nil' (it must be a position in the current
+ buffer), then it is the upper bound to the search. No match
+ extending after that position is accepted.
+
+ What happens when the search fails depends on the value of
+ NOERROR. If NOERROR is `nil', a `search-failed' error is
+ signaled. If NOERROR is `t', `re-search-forward' does nothing and
+ returns `nil'. If NOERROR is neither `nil' nor `t', then
+ `re-search-forward' moves point to LIMIT (or the end of the
+ buffer) and returns `nil'.
+
+ If REPEAT is supplied (it must be a positive number), then the
+ search is repeated that many times (each time starting at the end
+ of the previous time's match). If these successive searches
+ succeed, the function succeeds, moving point and returning its new
+ value. Otherwise the search fails.
+
+ In the following example, point is initially before the `T'.
+ Evaluating the search call moves point to the end of that line
+ (between the `t' of `hat' and the newline).
+
+ ---------- Buffer: foo ----------
+ I read "-!-The cat in the hat
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ (re-search-forward "[a-z]+" nil t 5)
+ => 27
+
+ ---------- Buffer: foo ----------
+ I read "The cat in the hat-!-
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ - Command: re-search-backward regexp &optional limit noerror repeat
+ This function searches backward in the current buffer for a string
+ of text that is matched by the regular expression REGEXP, leaving
+ point at the beginning of the first text found.
+
+ This function is analogous to `re-search-forward', but they are not
+ simple mirror images. `re-search-forward' finds the match whose
+ beginning is as close as possible to the starting point. If
+ `re-search-backward' were a perfect mirror image, it would find the
+ match whose end is as close as possible. However, in fact it
+ finds the match whose beginning is as close as possible. The
+ reason is that matching a regular expression at a given spot
+ always works from beginning to end, and starts at a specified
+ beginning position.
+
+ A true mirror-image of `re-search-forward' would require a special
+ feature for matching regexps from end to beginning. It's not
+ worth the trouble of implementing that.
+
+ - Function: string-match regexp string &optional start
+ This function returns the index of the start of the first match for
+ the regular expression REGEXP in STRING, or `nil' if there is no
+ match. If START is non-`nil', the search starts at that index in
+ STRING.
+
+ For example,
+
+ (string-match
+ "quick" "The quick brown fox jumped quickly.")
+ => 4
+ (string-match
+ "quick" "The quick brown fox jumped quickly." 8)
+ => 27
+
+ The index of the first character of the string is 0, the index of
+ the second character is 1, and so on.
+
+ After this function returns, the index of the first character
+ beyond the match is available as `(match-end 0)'. *Note Match
+ Data::.
+
+ (string-match
+ "quick" "The quick brown fox jumped quickly." 8)
+ => 27
+
+ (match-end 0)
+ => 32
+
+ - Function: split-string string &optional pattern
+ This function splits STRING to substrings delimited by PATTERN,
+ and returns a list of substrings. If PATTERN is omitted, it
+ defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by
+ white-space.
+
+ (split-string "foo bar")
+ => ("foo" "bar")
+
+ (split-string "something")
+ => ("something")
+
+ (split-string "a:b:c" ":")
+ => ("a" "b" "c")
+
+ (split-string ":a::b:c" ":")
+ => ("" "a" "" "b" "c")
+
+ - Function: split-path path
+ This function splits a search path into a list of strings. The
+ path components are separated with the characters specified with
+ `path-separator'. Under Unix, `path-separator' will normally be
+ `:', while under Windows, it will be `;'.
+
+ - Function: looking-at regexp
+ This function determines whether the text in the current buffer
+ directly following point matches the regular expression REGEXP.
+ "Directly following" means precisely that: the search is
+ "anchored" and it can succeed only starting with the first
+ character following point. The result is `t' if so, `nil'
+ otherwise.
+
+ This function does not move point, but it updates the match data,
+ which you can access using `match-beginning' and `match-end'.
+ *Note Match Data::.
+
+ In this example, point is located directly before the `T'. If it
+ were anywhere else, the result would be `nil'.
+
+ ---------- Buffer: foo ----------
+ I read "-!-The cat in the hat
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ (looking-at "The cat in the hat$")
+ => t
+
+\1f
+File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching
+
+POSIX Regular Expression Searching
+==================================
+
+ The usual regular expression functions do backtracking when necessary
+to handle the `\|' and repetition constructs, but they continue this
+only until they find _some_ match. Then they succeed and report the
+first match found.
+
+ This section describes alternative search functions which perform the
+full backtracking specified by the POSIX standard for regular expression
+matching. They continue backtracking until they have tried all
+possibilities and found all matches, so they can report the longest
+match, as required by POSIX. This is much slower, so use these
+functions only when you really need the longest match.
+
+ In Emacs versions prior to 19.29, these functions did not exist, and
+the functions described above implemented full POSIX backtracking.
+
+ - Function: posix-search-forward regexp &optional limit noerror repeat
+ This is like `re-search-forward' except that it performs the full
+ backtracking specified by the POSIX standard for regular expression
+ matching.
+
+ - Function: posix-search-backward regexp &optional limit noerror repeat
+ This is like `re-search-backward' except that it performs the full
+ backtracking specified by the POSIX standard for regular expression
+ matching.
+
+ - Function: posix-looking-at regexp
+ This is like `looking-at' except that it performs the full
+ backtracking specified by the POSIX standard for regular expression
+ matching.
+
+ - Function: posix-string-match regexp string &optional start
+ This is like `string-match' except that it performs the full
+ backtracking specified by the POSIX standard for regular expression
+ matching.
+
+\1f
+File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching
+
+Search and Replace
+==================
+
+ - Function: perform-replace from-string replacements query-flag
+ regexp-flag delimited-flag &optional repeat-count map
+ This function is the guts of `query-replace' and related commands.
+ It searches for occurrences of FROM-STRING and replaces some or
+ all of them. If QUERY-FLAG is `nil', it replaces all occurrences;
+ otherwise, it asks the user what to do about each one.
+
+ If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a
+ regular expression; otherwise, it must match literally. If
+ DELIMITED-FLAG is non-`nil', then only replacements surrounded by
+ word boundaries are considered.
+
+ The argument REPLACEMENTS specifies what to replace occurrences
+ with. If it is a string, that string is used. It can also be a
+ list of strings, to be used in cyclic order.
+
+ If REPEAT-COUNT is non-`nil', it should be an integer. Then it
+ specifies how many times to use each of the strings in the
+ REPLACEMENTS list before advancing cyclicly to the next one.
+
+ Normally, the keymap `query-replace-map' defines the possible user
+ responses for queries. The argument MAP, if non-`nil', is a
+ keymap to use instead of `query-replace-map'.
+
+ - Variable: query-replace-map
+ This variable holds a special keymap that defines the valid user
+ responses for `query-replace' and related functions, as well as
+ `y-or-n-p' and `map-y-or-n-p'. It is unusual in two ways:
+
+ * The "key bindings" are not commands, just symbols that are
+ meaningful to the functions that use this map.
+
+ * Prefix keys are not supported; each key binding must be for a
+ single event key sequence. This is because the functions
+ don't use read key sequence to get the input; instead, they
+ read a single event and look it up "by hand."
+
+ Here are the meaningful "bindings" for `query-replace-map'. Several
+of them are meaningful only for `query-replace' and friends.
+
+`act'
+ Do take the action being considered--in other words, "yes."
+
+`skip'
+ Do not take action for this question--in other words, "no."
+
+`exit'
+ Answer this question "no," and give up on the entire series of
+ questions, assuming that the answers will be "no."
+
+`act-and-exit'
+ Answer this question "yes," and give up on the entire series of
+ questions, assuming that subsequent answers will be "no."
+
+`act-and-show'
+ Answer this question "yes," but show the results--don't advance yet
+ to the next question.
+
+`automatic'
+ Answer this question and all subsequent questions in the series
+ with "yes," without further user interaction.
+
+`backup'
+ Move back to the previous place that a question was asked about.
+
+`edit'
+ Enter a recursive edit to deal with this question--instead of any
+ other action that would normally be taken.
+
+`delete-and-edit'
+ Delete the text being considered, then enter a recursive edit to
+ replace it.
+
+`recenter'
+ Redisplay and center the window, then ask the same question again.
+
+`quit'
+ Perform a quit right away. Only `y-or-n-p' and related functions
+ use this answer.
+
+`help'
+ Display some help, then ask again.
+
+\1f
+File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching
+
+The Match Data
+==============
+
+ XEmacs keeps track of the positions of the start and end of segments
+of text found during a regular expression search. This means, for
+example, that you can search for a complex pattern, such as a date in
+an Rmail message, and then extract parts of the match under control of
+the pattern.
+
+ Because the match data normally describe the most recent search only,
+you must be careful not to do another search inadvertently between the
+search you wish to refer back to and the use of the match data. If you
+can't avoid another intervening search, you must save and restore the
+match data around it, to prevent it from being overwritten.
+
+* Menu:
+
+* Simple Match Data:: Accessing single items of match data,
+ such as where a particular subexpression started.
+* Replacing Match:: Replacing a substring that was matched.
+* Entire Match Data:: Accessing the entire match data at once, as a list.
+* Saving Match Data:: Saving and restoring the match data.
+
+\1f
+File: lispref.info, Node: Simple Match Data, Next: Replacing Match, Up: Match Data
+
+Simple Match Data Access
+------------------------
+
+ This section explains how to use the match data to find out what was
+matched by the last search or match operation.
+
+ You can ask about the entire matching text, or about a particular
+parenthetical subexpression of a regular expression. The COUNT
+argument in the functions below specifies which. If COUNT is zero, you
+are asking about the entire match. If COUNT is positive, it specifies
+which subexpression you want.
+
+ Recall that the subexpressions of a regular expression are those
+expressions grouped with escaped parentheses, `\(...\)'. The COUNTth
+subexpression is found by counting occurrences of `\(' from the
+beginning of the whole regular expression. The first subexpression is
+numbered 1, the second 2, and so on. Only regular expressions can have
+subexpressions--after a simple string search, the only information
+available is about the entire match.
+
+ - Function: match-string count &optional in-string
+ This function returns, as a string, the text matched in the last
+ search or match operation. It returns the entire text if COUNT is
+ zero, or just the portion corresponding to the COUNTth
+ parenthetical subexpression, if COUNT is positive. If COUNT is
+ out of range, or if that subexpression didn't match anything, the
+ value is `nil'.
+
+ If the last such operation was done against a string with
+ `string-match', then you should pass the same string as the
+ argument IN-STRING. Otherwise, after a buffer search or match,
+ you should omit IN-STRING or pass `nil' for it; but you should
+ make sure that the current buffer when you call `match-string' is
+ the one in which you did the searching or matching.
+
+ - Function: match-beginning count
+ This function returns the position of the start of text matched by
+ the last regular expression searched for, or a subexpression of it.
+
+ If COUNT is zero, then the value is the position of the start of
+ the entire match. Otherwise, COUNT specifies a subexpression in
+ the regular expression, and the value of the function is the
+ starting position of the match for that subexpression.
+
+ The value is `nil' for a subexpression inside a `\|' alternative
+ that wasn't used in the match.
+
+ - Function: match-end count
+ This function is like `match-beginning' except that it returns the
+ position of the end of the match, rather than the position of the
+ beginning.
+
+ Here is an example of using the match data, with a comment showing
+the positions within the text:
+
+ (string-match "\\(qu\\)\\(ick\\)"
+ "The quick fox jumped quickly.")
+ ;0123456789
+ => 4
+
+ (match-string 0 "The quick fox jumped quickly.")
+ => "quick"
+ (match-string 1 "The quick fox jumped quickly.")
+ => "qu"
+ (match-string 2 "The quick fox jumped quickly.")
+ => "ick"
+
+ (match-beginning 1) ; The beginning of the match
+ => 4 ; with `qu' is at index 4.
+
+ (match-beginning 2) ; The beginning of the match
+ => 6 ; with `ick' is at index 6.
+
+ (match-end 1) ; The end of the match
+ => 6 ; with `qu' is at index 6.
+
+ (match-end 2) ; The end of the match
+ => 9 ; with `ick' is at index 9.
+
+ Here is another example. Point is initially located at the beginning
+of the line. Searching moves point to between the space and the word
+`in'. The beginning of the entire match is at the 9th character of the
+buffer (`T'), and the beginning of the match for the first
+subexpression is at the 13th character (`c').
+
+ (list
+ (re-search-forward "The \\(cat \\)")
+ (match-beginning 0)
+ (match-beginning 1))
+ => (9 9 13)
+
+ ---------- Buffer: foo ----------
+ I read "The cat -!-in the hat comes back" twice.
+ ^ ^
+ 9 13
+ ---------- Buffer: foo ----------
+
+(In this case, the index returned is a buffer position; the first
+character of the buffer counts as 1.)
+
+\1f
+File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data
+
+Replacing the Text That Matched
+-------------------------------
+
+ This function replaces the text matched by the last search with
+REPLACEMENT.
+
+ - Function: replace-match replacement &optional fixedcase literal
+ string
+ This function replaces the text in the buffer (or in STRING) that
+ was matched by the last search. It replaces that text with
+ REPLACEMENT.
+
+ If you did the last search in a buffer, you should specify `nil'
+ for STRING. Then `replace-match' does the replacement by editing
+ the buffer; it leaves point at the end of the replacement text,
+ and returns `t'.
+
+ If you did the search in a string, pass the same string as STRING.
+ Then `replace-match' does the replacement by constructing and
+ returning a new string.
+
+ If FIXEDCASE is non-`nil', then the case of the replacement text
+ is not changed; otherwise, the replacement text is converted to a
+ different case depending upon the capitalization of the text to be
+ replaced. If the original text is all upper case, the replacement
+ text is converted to upper case. If the first word of the
+ original text is capitalized, then the first word of the
+ replacement text is capitalized. If the original text contains
+ just one word, and that word is a capital letter, `replace-match'
+ considers this a capitalized first word rather than all upper case.
+
+ If `case-replace' is `nil', then case conversion is not done,
+ regardless of the value of FIXED-CASE. *Note Searching and Case::.
+
+ If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
+ it is, the only alterations being case changes as needed. If it
+ is `nil' (the default), then the character `\' is treated
+ specially. If a `\' appears in REPLACEMENT, then it must be part
+ of one of the following sequences:
+
+ `\&'
+ `\&' stands for the entire text being replaced.
+
+ `\N'
+ `\N', where N is a digit, stands for the text that matched
+ the Nth subexpression in the original regexp. Subexpressions
+ are those expressions grouped inside `\(...\)'.
+
+ `\\'
+ `\\' stands for a single `\' in the replacement text.
+
+\1f
File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data
Accessing the Entire Match Data
flag. Optional argument BUFFER defaults to the current buffer if
omitted.
-\1f
-File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
-
-Parsing Balanced Expressions
-============================
-
- Here are several functions for parsing and scanning balanced
-expressions, also known as "sexps", in which parentheses match in
-pairs. The syntax table controls the interpretation of characters, so
-these functions can be used for Lisp expressions when in Lisp mode and
-for C expressions when in C mode. *Note List Motion::, for convenient
-higher-level functions for moving over balanced expressions.
-
- - Function: parse-partial-sexp start limit &optional target-depth
- stop-before state stop-comment buffer
- This function parses a sexp in the current buffer starting at
- START, not scanning past LIMIT. It stops at position LIMIT or
- when certain criteria described below are met, and sets point to
- the location where parsing stops. It returns a value describing
- the status of the parse at the point where it stops.
-
- If STATE is `nil', START is assumed to be at the top level of
- parenthesis structure, such as the beginning of a function
- definition. Alternatively, you might wish to resume parsing in the
- middle of the structure. To do this, you must provide a STATE
- argument that describes the initial status of parsing.
-
- If the third argument TARGET-DEPTH is non-`nil', parsing stops if
- the depth in parentheses becomes equal to TARGET-DEPTH. The depth
- starts at 0, or at whatever is given in STATE.
-
- If the fourth argument STOP-BEFORE is non-`nil', parsing stops
- when it comes to any character that starts a sexp. If
- STOP-COMMENT is non-`nil', parsing stops when it comes to the
- start of a comment.
-
- The fifth argument STATE is an eight-element list of the same form
- as the value of this function, described below. The return value
- of one call may be used to initialize the state of the parse on
- another call to `parse-partial-sexp'.
-
- The result is a list of eight elements describing the final state
- of the parse:
-
- 0. The depth in parentheses, counting from 0.
-
- 1. The character position of the start of the innermost
- parenthetical grouping containing the stopping point; `nil'
- if none.
-
- 2. The character position of the start of the last complete
- subexpression terminated; `nil' if none.
-
- 3. Non-`nil' if inside a string. More precisely, this is the
- character that will terminate the string.
-
- 4. `t' if inside a comment (of either style).
-
- 5. `t' if point is just after a quote character.
-
- 6. The minimum parenthesis depth encountered during this scan.
-
- 7. `t' if inside a comment of style "b".
-
- Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
-
- This function is most often used to compute indentation for
- languages that have nested parentheses.
-
- - Function: scan-lists from count depth &optional buffer noerror
- This function scans forward COUNT balanced parenthetical groupings
- from character number FROM. It returns the character position
- where the scan stops.
-
- If DEPTH is nonzero, parenthesis depth counting begins from that
- value. The only candidates for stopping are places where the
- depth in parentheses becomes zero; `scan-lists' counts COUNT such
- places and then stops. Thus, a positive value for DEPTH means go
- out DEPTH levels of parenthesis.
-
- Scanning ignores comments if `parse-sexp-ignore-comments' is
- non-`nil'.
-
- If the scan reaches the beginning or end of the buffer (or its
- accessible portion), and the depth is not zero, an error is
- signaled. If the depth is zero but the count is not used up,
- `nil' is returned.
-
- If optional arg BUFFER is non-`nil', scanning occurs in that
- buffer instead of in the current buffer.
-
- If optional arg NOERROR is non-`nil', `scan-lists' will return
- `nil' instead of signalling an error.
-
- - Function: scan-sexps from count &optional buffer noerror
- This function scans forward COUNT sexps from character position
- FROM. It returns the character position where the scan stops.
-
- Scanning ignores comments if `parse-sexp-ignore-comments' is
- non-`nil'.
-
- If the scan reaches the beginning or end of (the accessible part
- of) the buffer in the middle of a parenthetical grouping, an error
- is signaled. If it reaches the beginning or end between groupings
- but before count is used up, `nil' is returned.
-
- If optional arg BUFFER is non-`nil', scanning occurs in that
- buffer instead of in the current buffer.
-
- If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
- instead of signalling an error.
-
- - Variable: parse-sexp-ignore-comments
- If the value is non-`nil', then comments are treated as whitespace
- by the functions in this section and by `forward-sexp'.
-
- In older Emacs versions, this feature worked only when the comment
- terminator is something like `*/', and appears only to end a
- comment. In languages where newlines terminate comments, it was
- necessary make this variable `nil', since not every newline is the
- end of a comment. This limitation no longer exists.
-
- You can use `forward-comment' to move forward or backward over one
-comment or several comments.
-
- - Function: forward-comment count &optional buffer
- This function moves point forward across COUNT comments (backward,
- if COUNT is negative). If it finds anything other than a comment
- or whitespace, it stops, leaving point at the place where it
- stopped. It also stops after satisfying COUNT.
-
- Optional argument BUFFER defaults to the current buffer.
-
- To move forward over all comments and whitespace following point, use
-`(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
-to use, because the number of comments in the buffer cannot exceed that
-many.
-
-\1f
-File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
-
-Some Standard Syntax Tables
-===========================
-
- Most of the major modes in XEmacs have their own syntax tables. Here
-are several of them:
-
- - Function: standard-syntax-table
- This function returns the standard syntax table, which is the
- syntax table used in Fundamental mode.
-
- - Variable: text-mode-syntax-table
- The value of this variable is the syntax table used in Text mode.
-
- - Variable: c-mode-syntax-table
- The value of this variable is the syntax table for C-mode buffers.
-
- - Variable: emacs-lisp-mode-syntax-table
- The value of this variable is the syntax table used in Emacs Lisp
- mode by editing commands. (It has no effect on the Lisp `read'
- function.)
-
-\1f
-File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
-
-Syntax Table Internals
-======================
-
- Each element of a syntax table is an integer that encodes the syntax
-of one character: the syntax class, possible matching character, and
-flags. Lisp programs don't usually work with the elements directly; the
-Lisp-level syntax table functions usually work with syntax descriptors
-(*note Syntax Descriptors::).
-
- The low 8 bits of each element of a syntax table indicate the syntax
-class.
-
-Integer
- Class
-
-0
- whitespace
-
-1
- punctuation
-
-2
- word
-
-3
- symbol
-
-4
- open parenthesis
-
-5
- close parenthesis
-
-6
- expression prefix
-
-7
- string quote
-
-8
- paired delimiter
-
-9
- escape
-
-10
- character quote
-
-11
- comment-start
-
-12
- comment-end
-
-13
- inherit
-
- The next 8 bits are the matching opposite parenthesis (if the
-character has parenthesis syntax); otherwise, they are not meaningful.
-The next 6 bits are the flags.
-
-\1f
-File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
-
-Abbrevs And Abbrev Expansion
-****************************
-
- An abbreviation or "abbrev" is a string of characters that may be
-expanded to a longer string. The user can insert the abbrev string and
-find it replaced automatically with the expansion of the abbrev. This
-saves typing.
-
- The set of abbrevs currently in effect is recorded in an "abbrev
-table". Each buffer has a local abbrev table, but normally all buffers
-in the same major mode share one abbrev table. There is also a global
-abbrev table. Normally both are used.
-
- An abbrev table is represented as an obarray containing a symbol for
-each abbreviation. The symbol's name is the abbreviation; its value is
-the expansion; its function definition is the hook function to do the
-expansion (*note Defining Abbrevs::); its property list cell contains
-the use count, the number of times the abbreviation has been expanded.
-Because these symbols are not interned in the usual obarray, they will
-never appear as the result of reading a Lisp expression; in fact,
-normally they are never used except by the code that handles abbrevs.
-Therefore, it is safe to use them in an extremely nonstandard way.
-*Note Creating Symbols::.
-
- For the user-level commands for abbrevs, see *Note Abbrev Mode:
-(emacs)Abbrevs.
-
-* Menu:
-
-* Abbrev Mode:: Setting up XEmacs for abbreviation.
-* Tables: Abbrev Tables. Creating and working with abbrev tables.
-* Defining Abbrevs:: Specifying abbreviations and their expansions.
-* Files: Abbrev Files. Saving abbrevs in files.
-* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
-* Standard Abbrev Tables:: Abbrev tables used by various major modes.
-
-\1f
-File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
-
-Setting Up Abbrev Mode
-======================
-
- Abbrev mode is a minor mode controlled by the value of the variable
-`abbrev-mode'.
-
- - Variable: abbrev-mode
- A non-`nil' value of this variable turns on the automatic expansion
- of abbrevs when their abbreviations are inserted into a buffer.
- If the value is `nil', abbrevs may be defined, but they are not
- expanded automatically.
-
- This variable automatically becomes local when set in any fashion.
-
- - Variable: default-abbrev-mode
- This is the value of `abbrev-mode' for buffers that do not
- override it. This is the same as `(default-value 'abbrev-mode)'.
-
-\1f
-File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
-
-Abbrev Tables
-=============
-
- This section describes how to create and manipulate abbrev tables.
-
- - Function: make-abbrev-table
- This function creates and returns a new, empty abbrev table--an
- obarray containing no symbols. It is a vector filled with zeros.
-
- - Function: clear-abbrev-table table
- This function undefines all the abbrevs in abbrev table TABLE,
- leaving it empty. The function returns `nil'.
-
- - Function: define-abbrev-table tabname definitions
- This function defines TABNAME (a symbol) as an abbrev table name,
- i.e., as a variable whose value is an abbrev table. It defines
- abbrevs in the table according to DEFINITIONS, a list of elements
- of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The value is
- always `nil'.
-
- - Variable: abbrev-table-name-list
- This is a list of symbols whose values are abbrev tables.
- `define-abbrev-table' adds the new abbrev table name to this list.
-
- - Function: insert-abbrev-table-description name &optional human
- This function inserts before point a description of the abbrev
- table named NAME. The argument NAME is a symbol whose value is an
- abbrev table. The value is always `nil'.
-
- If HUMAN is non-`nil', the description is human-oriented.
- Otherwise the description is a Lisp expression--a call to
- `define-abbrev-table' that would define NAME exactly as it is
- currently defined.
-
-\1f
-File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
-
-Defining Abbrevs
-================
-
- These functions define an abbrev in a specified abbrev table.
-`define-abbrev' is the low-level basic function, while `add-abbrev' is
-used by commands that ask for information from the user.
-
- - Function: add-abbrev table type arg
- This function adds an abbreviation to abbrev table TABLE based on
- information from the user. The argument TYPE is a string
- describing in English the kind of abbrev this will be (typically,
- `"global"' or `"mode-specific"'); this is used in prompting the
- user. The argument ARG is the number of words in the expansion.
-
- The return value is the symbol that internally represents the new
- abbrev, or `nil' if the user declines to confirm redefining an
- existing abbrev.
-
- - Function: define-abbrev table name expansion hook
- This function defines an abbrev in TABLE named NAME, to expand to
- EXPANSION, and call HOOK. The return value is an uninterned
- symbol that represents the abbrev inside XEmacs; its name is NAME.
-
- The argument NAME should be a string. The argument EXPANSION
- should be a string, or `nil' to undefine the abbrev.
-
- The argument HOOK is a function or `nil'. If HOOK is non-`nil',
- then it is called with no arguments after the abbrev is replaced
- with EXPANSION; point is located at the end of EXPANSION when HOOK
- is called.
-
- The use count of the abbrev is initialized to zero.
-
- - User Option: only-global-abbrevs
- If this variable is non-`nil', it means that the user plans to use
- global abbrevs only. This tells the commands that define
- mode-specific abbrevs to define global ones instead. This
- variable does not alter the behavior of the functions in this
- section; it is examined by their callers.
-
-\1f
-File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
-
-Saving Abbrevs in Files
-=======================
-
- A file of saved abbrev definitions is actually a file of Lisp code.
-The abbrevs are saved in the form of a Lisp program to define the same
-abbrev tables with the same contents. Therefore, you can load the file
-with `load' (*note How Programs Do Loading::). However, the function
-`quietly-read-abbrev-file' is provided as a more convenient interface.
-
- User-level facilities such as `save-some-buffers' can save abbrevs
-in a file automatically, under the control of variables described here.
-
- - User Option: abbrev-file-name
- This is the default file name for reading and saving abbrevs.
-
- - Function: quietly-read-abbrev-file filename
- This function reads abbrev definitions from a file named FILENAME,
- previously written with `write-abbrev-file'. If FILENAME is
- `nil', the file specified in `abbrev-file-name' is used.
- `save-abbrevs' is set to `t' so that changes will be saved.
-
- This function does not display any messages. It returns `nil'.
-
- - User Option: save-abbrevs
- A non-`nil' value for `save-abbrev' means that XEmacs should save
- abbrevs when files are saved. `abbrev-file-name' specifies the
- file to save the abbrevs in.
-
- - Variable: abbrevs-changed
- This variable is set non-`nil' by defining or altering any
- abbrevs. This serves as a flag for various XEmacs commands to
- offer to save your abbrevs.
-
- - Command: write-abbrev-file filename
- Save all abbrev definitions, in all abbrev tables, in the file
- FILENAME, in the form of a Lisp program that when loaded will
- define the same abbrevs. This function returns `nil'.
-
-\1f
-File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
-
-Looking Up and Expanding Abbreviations
-======================================
-
- Abbrevs are usually expanded by commands for interactive use,
-including `self-insert-command'. This section describes the
-subroutines used in writing such functions, as well as the variables
-they use for communication.
-
- - Function: abbrev-symbol abbrev &optional table
- This function returns the symbol representing the abbrev named
- ABBREV. The value returned is `nil' if that abbrev is not
- defined. The optional second argument TABLE is the abbrev table
- to look it up in. If TABLE is `nil', this function tries first
- the current buffer's local abbrev table, and second the global
- abbrev table.
-
- - Function: abbrev-expansion abbrev &optional table
- This function returns the string that ABBREV would expand into (as
- defined by the abbrev tables used for the current buffer). The
- optional argument TABLE specifies the abbrev table to use, as in
- `abbrev-symbol'.
-
- - Command: expand-abbrev
- This command expands the abbrev before point, if any. If point
- does not follow an abbrev, this command does nothing. The command
- returns `t' if it did expansion, `nil' otherwise.
-
- - Command: abbrev-prefix-mark &optional arg
- Mark current point as the beginning of an abbrev. The next call to
- `expand-abbrev' will use the text from here to point (where it is
- then) as the abbrev to expand, rather than using the previous word
- as usual.
-
- - User Option: abbrev-all-caps
- When this is set non-`nil', an abbrev entered entirely in upper
- case is expanded using all upper case. Otherwise, an abbrev
- entered entirely in upper case is expanded by capitalizing each
- word of the expansion.
-
- - Variable: abbrev-start-location
- This is the buffer position for `expand-abbrev' to use as the start
- of the next abbrev to be expanded. (`nil' means use the word
- before point instead.) `abbrev-start-location' is set to `nil'
- each time `expand-abbrev' is called. This variable is also set by
- `abbrev-prefix-mark'.
-
- - Variable: abbrev-start-location-buffer
- The value of this variable is the buffer for which
- `abbrev-start-location' has been set. Trying to expand an abbrev
- in any other buffer clears `abbrev-start-location'. This variable
- is set by `abbrev-prefix-mark'.
-
- - Variable: last-abbrev
- This is the `abbrev-symbol' of the last abbrev expanded. This
- information is left by `expand-abbrev' for the sake of the
- `unexpand-abbrev' command.
-
- - Variable: last-abbrev-location
- This is the location of the last abbrev expanded. This contains
- information left by `expand-abbrev' for the sake of the
- `unexpand-abbrev' command.
-
- - Variable: last-abbrev-text
- This is the exact expansion text of the last abbrev expanded,
- after case conversion (if any). Its value is `nil' if the abbrev
- has already been unexpanded. This contains information left by
- `expand-abbrev' for the sake of the `unexpand-abbrev' command.
-
- - Variable: pre-abbrev-expand-hook
- This is a normal hook whose functions are executed, in sequence,
- just before any expansion of an abbrev. *Note Hooks::. Since it
- is a normal hook, the hook functions receive no arguments.
- However, they can find the abbrev to be expanded by looking in the
- buffer before point.
-
- The following sample code shows a simple use of
-`pre-abbrev-expand-hook'. If the user terminates an abbrev with a
-punctuation character, the hook function asks for confirmation. Thus,
-this hook allows the user to decide whether to expand the abbrev, and
-aborts expansion if it is not confirmed.
-
- (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
-
- ;; This is the function invoked by `pre-abbrev-expand-hook'.
-
- ;; If the user terminated the abbrev with a space, the function does
- ;; nothing (that is, it returns so that the abbrev can expand). If the
- ;; user entered some other character, this function asks whether
- ;; expansion should continue.
-
- ;; If the user answers the prompt with `y', the function returns
- ;; `nil' (because of the `not' function), but that is
- ;; acceptable; the return value has no effect on expansion.
-
- (defun query-if-not-space ()
- (if (/= ?\ (preceding-char))
- (if (not (y-or-n-p "Do you want to expand this abbrev? "))
- (error "Not expanding this abbrev"))))
-
-\1f
-File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
-
-Standard Abbrev Tables
-======================
-
- Here we list the variables that hold the abbrev tables for the
-preloaded major modes of XEmacs.
-
- - Variable: global-abbrev-table
- This is the abbrev table for mode-independent abbrevs. The abbrevs
- defined in it apply to all buffers. Each buffer may also have a
- local abbrev table, whose abbrev definitions take precedence over
- those in the global table.
-
- - Variable: local-abbrev-table
- The value of this buffer-local variable is the (mode-specific)
- abbreviation table of the current buffer.
-
- - Variable: fundamental-mode-abbrev-table
- This is the local abbrev table used in Fundamental mode; in other
- words, it is the local abbrev table in all buffers in Fundamental
- mode.
-
- - Variable: text-mode-abbrev-table
- This is the local abbrev table used in Text mode.
-
- - Variable: c-mode-abbrev-table
- This is the local abbrev table used in C mode.
-
- - Variable: lisp-mode-abbrev-table
- This is the local abbrev table used in Lisp mode and Emacs Lisp
- mode.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
+
+Parsing Balanced Expressions
+============================
+
+ Here are several functions for parsing and scanning balanced
+expressions, also known as "sexps", in which parentheses match in
+pairs. The syntax table controls the interpretation of characters, so
+these functions can be used for Lisp expressions when in Lisp mode and
+for C expressions when in C mode. *Note List Motion::, for convenient
+higher-level functions for moving over balanced expressions.
+
+ - Function: parse-partial-sexp start limit &optional target-depth
+ stop-before state stop-comment buffer
+ This function parses a sexp in the current buffer starting at
+ START, not scanning past LIMIT. It stops at position LIMIT or
+ when certain criteria described below are met, and sets point to
+ the location where parsing stops. It returns a value describing
+ the status of the parse at the point where it stops.
+
+ If STATE is `nil', START is assumed to be at the top level of
+ parenthesis structure, such as the beginning of a function
+ definition. Alternatively, you might wish to resume parsing in the
+ middle of the structure. To do this, you must provide a STATE
+ argument that describes the initial status of parsing.
+
+ If the third argument TARGET-DEPTH is non-`nil', parsing stops if
+ the depth in parentheses becomes equal to TARGET-DEPTH. The depth
+ starts at 0, or at whatever is given in STATE.
+
+ If the fourth argument STOP-BEFORE is non-`nil', parsing stops
+ when it comes to any character that starts a sexp. If
+ STOP-COMMENT is non-`nil', parsing stops when it comes to the
+ start of a comment.
+
+ The fifth argument STATE is an eight-element list of the same form
+ as the value of this function, described below. The return value
+ of one call may be used to initialize the state of the parse on
+ another call to `parse-partial-sexp'.
+
+ The result is a list of eight elements describing the final state
+ of the parse:
+
+ 0. The depth in parentheses, counting from 0.
+
+ 1. The character position of the start of the innermost
+ parenthetical grouping containing the stopping point; `nil'
+ if none.
+
+ 2. The character position of the start of the last complete
+ subexpression terminated; `nil' if none.
+
+ 3. Non-`nil' if inside a string. More precisely, this is the
+ character that will terminate the string.
+
+ 4. `t' if inside a comment (of either style).
+
+ 5. `t' if point is just after a quote character.
+
+ 6. The minimum parenthesis depth encountered during this scan.
+
+ 7. `t' if inside a comment of style "b".
+
+ Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
+
+ This function is most often used to compute indentation for
+ languages that have nested parentheses.
+
+ - Function: scan-lists from count depth &optional buffer noerror
+ This function scans forward COUNT balanced parenthetical groupings
+ from character number FROM. It returns the character position
+ where the scan stops.
+
+ If DEPTH is nonzero, parenthesis depth counting begins from that
+ value. The only candidates for stopping are places where the
+ depth in parentheses becomes zero; `scan-lists' counts COUNT such
+ places and then stops. Thus, a positive value for DEPTH means go
+ out DEPTH levels of parenthesis.
+
+ Scanning ignores comments if `parse-sexp-ignore-comments' is
+ non-`nil'.
+
+ If the scan reaches the beginning or end of the buffer (or its
+ accessible portion), and the depth is not zero, an error is
+ signaled. If the depth is zero but the count is not used up,
+ `nil' is returned.
+
+ If optional arg BUFFER is non-`nil', scanning occurs in that
+ buffer instead of in the current buffer.
+
+ If optional arg NOERROR is non-`nil', `scan-lists' will return
+ `nil' instead of signalling an error.
+
+ - Function: scan-sexps from count &optional buffer noerror
+ This function scans forward COUNT sexps from character position
+ FROM. It returns the character position where the scan stops.
+
+ Scanning ignores comments if `parse-sexp-ignore-comments' is
+ non-`nil'.
+
+ If the scan reaches the beginning or end of (the accessible part
+ of) the buffer in the middle of a parenthetical grouping, an error
+ is signaled. If it reaches the beginning or end between groupings
+ but before count is used up, `nil' is returned.
+
+ If optional arg BUFFER is non-`nil', scanning occurs in that
+ buffer instead of in the current buffer.
+
+ If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
+ instead of signalling an error.
+
+ - Variable: parse-sexp-ignore-comments
+ If the value is non-`nil', then comments are treated as whitespace
+ by the functions in this section and by `forward-sexp'.
+
+ In older Emacs versions, this feature worked only when the comment
+ terminator is something like `*/', and appears only to end a
+ comment. In languages where newlines terminate comments, it was
+ necessary make this variable `nil', since not every newline is the
+ end of a comment. This limitation no longer exists.
+
+ You can use `forward-comment' to move forward or backward over one
+comment or several comments.
+
+ - Function: forward-comment count &optional buffer
+ This function moves point forward across COUNT comments (backward,
+ if COUNT is negative). If it finds anything other than a comment
+ or whitespace, it stops, leaving point at the place where it
+ stopped. It also stops after satisfying COUNT.
+
+ Optional argument BUFFER defaults to the current buffer.
+
+ To move forward over all comments and whitespace following point, use
+`(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
+to use, because the number of comments in the buffer cannot exceed that
+many.
+
+\1f
+File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
+
+Some Standard Syntax Tables
+===========================
+
+ Most of the major modes in XEmacs have their own syntax tables. Here
+are several of them:
+
+ - Function: standard-syntax-table
+ This function returns the standard syntax table, which is the
+ syntax table used in Fundamental mode.
+
+ - Variable: text-mode-syntax-table
+ The value of this variable is the syntax table used in Text mode.
+
+ - Variable: c-mode-syntax-table
+ The value of this variable is the syntax table for C-mode buffers.
+
+ - Variable: emacs-lisp-mode-syntax-table
+ The value of this variable is the syntax table used in Emacs Lisp
+ mode by editing commands. (It has no effect on the Lisp `read'
+ function.)
+
+\1f
+File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
+
+Syntax Table Internals
+======================
+
+ Each element of a syntax table is an integer that encodes the syntax
+of one character: the syntax class, possible matching character, and
+flags. Lisp programs don't usually work with the elements directly; the
+Lisp-level syntax table functions usually work with syntax descriptors
+(*note Syntax Descriptors::).
+
+ The low 8 bits of each element of a syntax table indicate the syntax
+class.
+
+Integer
+ Class
+
+0
+ whitespace
+
+1
+ punctuation
+
+2
+ word
+
+3
+ symbol
+
+4
+ open parenthesis
+
+5
+ close parenthesis
+
+6
+ expression prefix
+
+7
+ string quote
+
+8
+ paired delimiter
+
+9
+ escape
+
+10
+ character quote
+
+11
+ comment-start
+
+12
+ comment-end
+
+13
+ inherit
+
+ The next 8 bits are the matching opposite parenthesis (if the
+character has parenthesis syntax); otherwise, they are not meaningful.
+The next 6 bits are the flags.
+
+\1f
+File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
+
+Abbrevs And Abbrev Expansion
+****************************
+
+ An abbreviation or "abbrev" is a string of characters that may be
+expanded to a longer string. The user can insert the abbrev string and
+find it replaced automatically with the expansion of the abbrev. This
+saves typing.
+
+ The set of abbrevs currently in effect is recorded in an "abbrev
+table". Each buffer has a local abbrev table, but normally all buffers
+in the same major mode share one abbrev table. There is also a global
+abbrev table. Normally both are used.
+
+ An abbrev table is represented as an obarray containing a symbol for
+each abbreviation. The symbol's name is the abbreviation; its value is
+the expansion; its function definition is the hook function to do the
+expansion (*note Defining Abbrevs::); its property list cell contains
+the use count, the number of times the abbreviation has been expanded.
+Because these symbols are not interned in the usual obarray, they will
+never appear as the result of reading a Lisp expression; in fact,
+normally they are never used except by the code that handles abbrevs.
+Therefore, it is safe to use them in an extremely nonstandard way.
+*Note Creating Symbols::.
+
+ For the user-level commands for abbrevs, see *Note Abbrev Mode:
+(emacs)Abbrevs.
+
+* Menu:
+
+* Abbrev Mode:: Setting up XEmacs for abbreviation.
+* Tables: Abbrev Tables. Creating and working with abbrev tables.
+* Defining Abbrevs:: Specifying abbreviations and their expansions.
+* Files: Abbrev Files. Saving abbrevs in files.
+* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables:: Abbrev tables used by various major modes.
+
+\1f
+File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
+
+Setting Up Abbrev Mode
+======================
+
+ Abbrev mode is a minor mode controlled by the value of the variable
+`abbrev-mode'.
+
+ - Variable: abbrev-mode
+ A non-`nil' value of this variable turns on the automatic expansion
+ of abbrevs when their abbreviations are inserted into a buffer.
+ If the value is `nil', abbrevs may be defined, but they are not
+ expanded automatically.
+
+ This variable automatically becomes local when set in any fashion.
+
+ - Variable: default-abbrev-mode
+ This is the value of `abbrev-mode' for buffers that do not
+ override it. This is the same as `(default-value 'abbrev-mode)'.
+
+\1f
+File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
+
+Abbrev Tables
+=============
+
+ This section describes how to create and manipulate abbrev tables.
+
+ - Function: make-abbrev-table
+ This function creates and returns a new, empty abbrev table--an
+ obarray containing no symbols. It is a vector filled with zeros.
+
+ - Function: clear-abbrev-table table
+ This function undefines all the abbrevs in abbrev table TABLE,
+ leaving it empty. The function returns `nil'.
+
+ - Function: define-abbrev-table tabname definitions
+ This function defines TABNAME (a symbol) as an abbrev table name,
+ i.e., as a variable whose value is an abbrev table. It defines
+ abbrevs in the table according to DEFINITIONS, a list of elements
+ of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The value is
+ always `nil'.
+
+ - Variable: abbrev-table-name-list
+ This is a list of symbols whose values are abbrev tables.
+ `define-abbrev-table' adds the new abbrev table name to this list.
+
+ - Function: insert-abbrev-table-description name &optional human
+ This function inserts before point a description of the abbrev
+ table named NAME. The argument NAME is a symbol whose value is an
+ abbrev table. The value is always `nil'.
+
+ If HUMAN is non-`nil', the description is human-oriented.
+ Otherwise the description is a Lisp expression--a call to
+ `define-abbrev-table' that would define NAME exactly as it is
+ currently defined.
+
+\1f
+File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
+
+Defining Abbrevs
+================
+
+ These functions define an abbrev in a specified abbrev table.
+`define-abbrev' is the low-level basic function, while `add-abbrev' is
+used by commands that ask for information from the user.
+
+ - Function: add-abbrev table type arg
+ This function adds an abbreviation to abbrev table TABLE based on
+ information from the user. The argument TYPE is a string
+ describing in English the kind of abbrev this will be (typically,
+ `"global"' or `"mode-specific"'); this is used in prompting the
+ user. The argument ARG is the number of words in the expansion.
+
+ The return value is the symbol that internally represents the new
+ abbrev, or `nil' if the user declines to confirm redefining an
+ existing abbrev.
+
+ - Function: define-abbrev table name expansion hook
+ This function defines an abbrev in TABLE named NAME, to expand to
+ EXPANSION, and call HOOK. The return value is an uninterned
+ symbol that represents the abbrev inside XEmacs; its name is NAME.
+
+ The argument NAME should be a string. The argument EXPANSION
+ should be a string, or `nil' to undefine the abbrev.
+
+ The argument HOOK is a function or `nil'. If HOOK is non-`nil',
+ then it is called with no arguments after the abbrev is replaced
+ with EXPANSION; point is located at the end of EXPANSION when HOOK
+ is called.
+
+ The use count of the abbrev is initialized to zero.
+
+ - User Option: only-global-abbrevs
+ If this variable is non-`nil', it means that the user plans to use
+ global abbrevs only. This tells the commands that define
+ mode-specific abbrevs to define global ones instead. This
+ variable does not alter the behavior of the functions in this
+ section; it is examined by their callers.
+
+\1f
+File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
+
+Saving Abbrevs in Files
+=======================
+
+ A file of saved abbrev definitions is actually a file of Lisp code.
+The abbrevs are saved in the form of a Lisp program to define the same
+abbrev tables with the same contents. Therefore, you can load the file
+with `load' (*note How Programs Do Loading::). However, the function
+`quietly-read-abbrev-file' is provided as a more convenient interface.
+
+ User-level facilities such as `save-some-buffers' can save abbrevs
+in a file automatically, under the control of variables described here.
+
+ - User Option: abbrev-file-name
+ This is the default file name for reading and saving abbrevs.
+
+ - Function: quietly-read-abbrev-file filename
+ This function reads abbrev definitions from a file named FILENAME,
+ previously written with `write-abbrev-file'. If FILENAME is
+ `nil', the file specified in `abbrev-file-name' is used.
+ `save-abbrevs' is set to `t' so that changes will be saved.
+
+ This function does not display any messages. It returns `nil'.
+
+ - User Option: save-abbrevs
+ A non-`nil' value for `save-abbrev' means that XEmacs should save
+ abbrevs when files are saved. `abbrev-file-name' specifies the
+ file to save the abbrevs in.
+
+ - Variable: abbrevs-changed
+ This variable is set non-`nil' by defining or altering any
+ abbrevs. This serves as a flag for various XEmacs commands to
+ offer to save your abbrevs.
+
+ - Command: write-abbrev-file filename
+ Save all abbrev definitions, in all abbrev tables, in the file
+ FILENAME, in the form of a Lisp program that when loaded will
+ define the same abbrevs. This function returns `nil'.
+
+\1f
+File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
+
+Looking Up and Expanding Abbreviations
+======================================
+
+ Abbrevs are usually expanded by commands for interactive use,
+including `self-insert-command'. This section describes the
+subroutines used in writing such functions, as well as the variables
+they use for communication.
+
+ - Function: abbrev-symbol abbrev &optional table
+ This function returns the symbol representing the abbrev named
+ ABBREV. The value returned is `nil' if that abbrev is not
+ defined. The optional second argument TABLE is the abbrev table
+ to look it up in. If TABLE is `nil', this function tries first
+ the current buffer's local abbrev table, and second the global
+ abbrev table.
+
+ - Function: abbrev-expansion abbrev &optional table
+ This function returns the string that ABBREV would expand into (as
+ defined by the abbrev tables used for the current buffer). The
+ optional argument TABLE specifies the abbrev table to use, as in
+ `abbrev-symbol'.
+
+ - Command: expand-abbrev
+ This command expands the abbrev before point, if any. If point
+ does not follow an abbrev, this command does nothing. The command
+ returns `t' if it did expansion, `nil' otherwise.
+
+ - Command: abbrev-prefix-mark &optional arg
+ Mark current point as the beginning of an abbrev. The next call to
+ `expand-abbrev' will use the text from here to point (where it is
+ then) as the abbrev to expand, rather than using the previous word
+ as usual.
+
+ - User Option: abbrev-all-caps
+ When this is set non-`nil', an abbrev entered entirely in upper
+ case is expanded using all upper case. Otherwise, an abbrev
+ entered entirely in upper case is expanded by capitalizing each
+ word of the expansion.
+
+ - Variable: abbrev-start-location
+ This is the buffer position for `expand-abbrev' to use as the start
+ of the next abbrev to be expanded. (`nil' means use the word
+ before point instead.) `abbrev-start-location' is set to `nil'
+ each time `expand-abbrev' is called. This variable is also set by
+ `abbrev-prefix-mark'.
+
+ - Variable: abbrev-start-location-buffer
+ The value of this variable is the buffer for which
+ `abbrev-start-location' has been set. Trying to expand an abbrev
+ in any other buffer clears `abbrev-start-location'. This variable
+ is set by `abbrev-prefix-mark'.
+
+ - Variable: last-abbrev
+ This is the `abbrev-symbol' of the last abbrev expanded. This
+ information is left by `expand-abbrev' for the sake of the
+ `unexpand-abbrev' command.
+
+ - Variable: last-abbrev-location
+ This is the location of the last abbrev expanded. This contains
+ information left by `expand-abbrev' for the sake of the
+ `unexpand-abbrev' command.
+
+ - Variable: last-abbrev-text
+ This is the exact expansion text of the last abbrev expanded,
+ after case conversion (if any). Its value is `nil' if the abbrev
+ has already been unexpanded. This contains information left by
+ `expand-abbrev' for the sake of the `unexpand-abbrev' command.
+
+ - Variable: pre-abbrev-expand-hook
+ This is a normal hook whose functions are executed, in sequence,
+ just before any expansion of an abbrev. *Note Hooks::. Since it
+ is a normal hook, the hook functions receive no arguments.
+ However, they can find the abbrev to be expanded by looking in the
+ buffer before point.
+
+ The following sample code shows a simple use of
+`pre-abbrev-expand-hook'. If the user terminates an abbrev with a
+punctuation character, the hook function asks for confirmation. Thus,
+this hook allows the user to decide whether to expand the abbrev, and
+aborts expansion if it is not confirmed.
+
+ (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
+
+ ;; This is the function invoked by `pre-abbrev-expand-hook'.
+
+ ;; If the user terminated the abbrev with a space, the function does
+ ;; nothing (that is, it returns so that the abbrev can expand). If the
+ ;; user entered some other character, this function asks whether
+ ;; expansion should continue.
+
+ ;; If the user answers the prompt with `y', the function returns
+ ;; `nil' (because of the `not' function), but that is
+ ;; acceptable; the return value has no effect on expansion.
+
+ (defun query-if-not-space ()
+ (if (/= ?\ (preceding-char))
+ (if (not (y-or-n-p "Do you want to expand this abbrev? "))
+ (error "Not expanding this abbrev"))))
+
+\1f
+File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
+
+Standard Abbrev Tables
+======================
+
+ Here we list the variables that hold the abbrev tables for the
+preloaded major modes of XEmacs.
+
+ - Variable: global-abbrev-table
+ This is the abbrev table for mode-independent abbrevs. The abbrevs
+ defined in it apply to all buffers. Each buffer may also have a
+ local abbrev table, whose abbrev definitions take precedence over
+ those in the global table.
+
+ - Variable: local-abbrev-table
+ The value of this buffer-local variable is the (mode-specific)
+ abbreviation table of the current buffer.
+
+ - Variable: fundamental-mode-abbrev-table
+ This is the local abbrev table used in Fundamental mode; in other
+ words, it is the local abbrev table in all buffers in Fundamental
+ mode.
+
+ - Variable: text-mode-abbrev-table
+ This is the local abbrev table used in Text mode.
+
+ - Variable: c-mode-abbrev-table
+ This is the local abbrev table used in C mode.
+
+ - Variable: lisp-mode-abbrev-table
+ This is the local abbrev table used in Lisp mode and Emacs Lisp
+ mode.
+
+\1f
File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top
Extents
This function returns T if `map-extents' would visit EXTENT if
called with the given arguments.
-\1f
-File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
-
-Properties of Extents
-=====================
-
- Each extent has a property list associating property names with
-values. Some property names have predefined meanings, and can usually
-only assume particular values. Assigning other values to such a
-property either cause the value to be converted into a legal value
-(e.g., assigning anything but `nil' to a Boolean property will cause
-the value of `t' to be assigned to the property) or will cause an
-error. Property names without predefined meanings can be assigned any
-value. An undefined property is equivalent to a property with a value
-of `nil', or with a particular default value in the case of properties
-with predefined meanings. Note that, when an extent is created, the
-`end-open' and `detachable' properties are set on it.
-
- If an extent has a parent, all of its properties actually derive
-from that parent (or from the root ancestor if the parent in turn has a
-parent), and setting a property of the extent actually sets that
-property on the parent. *Note Extent Parents::.
-
- - Function: extent-property extent property
- This function returns the value of PROPERTY in EXTENT. If
- PROPERTY is undefined, `nil' is returned.
-
- - Function: extent-properties extent
- This function returns a list of all of EXTENT's properties that do
- not have the value of `nil' (or the default value, for properties
- with predefined meanings).
-
- - Function: set-extent-property extent property value
- This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
- predefined meaning, only certain values are allowed, and some
- values may be converted to others before being stored.)
-
- - Function: set-extent-properties extent plist
- Change some properties of EXTENT. PLIST is a property list. This
- is useful to change many extent properties at once.
-
- The following table lists the properties with predefined meanings,
-along with their allowable values.
-
-`detached'
- (Boolean) Whether the extent is detached. Setting this is the
- same as calling `detach-extent'. *Note Detached Extents::.
-
-`destroyed'
- (Boolean) Whether the extent has been deleted. Setting this is
- the same as calling `delete-extent'.
-
-`priority'
- (integer) The extent's redisplay priority. Defaults to 0. *Note
- priority: Intro to Extents. This property can also be set with
- `set-extent-priority' and accessed with `extent-priority'.
-
-`start-open'
- (Boolean) Whether the start position of the extent is open,
- meaning that characters inserted at that position go outside of
- the extent. *Note Extent Endpoints::.
-
-`start-closed'
- (Boolean) Same as `start-open' but with the opposite sense.
- Setting this property clears `start-open' and vice-versa.
-
-`end-open'
- (Boolean) Whether the end position of the extent is open, meaning
- that characters inserted at that position go outside of the
- extent. This is `t' by default. *Note Extent Endpoints::.
-
-`end-closed'
- (Boolean) Same as `end-open' but with the opposite sense. Setting
- this property clears `end-open' and vice-versa.
-
-`read-only'
- (Boolean) Whether text within this extent will be unmodifiable.
-
-`face'
- (face, face name, list of faces or face names, or `nil') The face
- in which to display the extent's text. This property can also be
- set with `set-extent-face' and accessed with `extent-face'. Note
- that if a list of faces is specified, the faces are merged
- together, with faces earlier in the list having priority over
- faces later in the list.
-
-`mouse-face'
- (face, face name, list of faces or face names, or `nil') The face
- used to display the extent when the mouse moves over it. This
- property can also be set with `set-extent-mouse-face' and accessed
- with `extent-mouse-face'. Note that if a list of faces is
- specified, the faces are merged together, with faces earlier in
- the list having priority over faces later in the list. *Note
- Extents and Events::.
-
-`pointer'
- (pointer glyph) The glyph used as the pointer when the mouse
- moves over the extent. This takes precedence over the
- `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
- for any reason this glyph is an invalid pointer, the standard
- glyphs will be used as fallbacks. *Note Mouse Pointer::.
-
-`detachable'
- (Boolean) Whether this extent becomes detached when all of the
- text it covers is deleted. This is `t' by default. *Note
- Detached Extents::.
-
-`duplicable'
- (Boolean) Whether this extent should be copied into strings, so
- that kill, yank, and undo commands will restore or copy it. *Note
- Duplicable Extents::.
-
-`unique'
- (Boolean) Meaningful only in conjunction with `duplicable'. When
- this is set, there may be only one instance of this extent
- attached at a time. *Note Duplicable Extents::.
-
-`invisible'
- (Boolean) If `t', text under this extent will not be displayed -
- it will look as if the text is not there at all.
-
-`keymap'
- (keymap or `nil') This keymap is consulted for mouse clicks on this
- extent or keypresses made while `point' is within the extent.
- *Note Extents and Events::.
-
-`copy-function'
- This is a hook that is run when a duplicable extent is about to be
- copied from a buffer to a string (or the kill ring). *Note
- Duplicable Extents::.
-
-`paste-function'
- This is a hook that is run when a duplicable extent is about to be
- copied from a string (or the kill ring) into a buffer. *Note
- Duplicable Extents::.
-
-`begin-glyph'
- (glyph or `nil') This extent's begin glyph. *Note Annotations::.
-
-`end-glyph'
- (glyph or `nil') This extent's end glyph. *Note Annotations::.
-
-`begin-glyph-layout'
- (`text', `whitespace', `inside-margin', or `outside-margin') The
- layout policy for this extent's begin glyph. Defaults to `text'.
- *Note Annotations::.
-
-`end-glyph-layout'
- (`text', `whitespace', `inside-margin', or `outside-margin') The
- layout policy for this extent's end glyph. Defaults to `text'.
- *Note Annotations::.
-
-`initial-redisplay-function'
- (any funcallable object) The function to be called the first time
- (a part of) the extent is redisplayed. It will be called with the
- extent as its argument.
-
- This is used by `lazy-shot' to implement lazy font-locking. The
- functionality is still experimental, and may change without further
- notice.
-
- The following convenience functions are provided for accessing
-particular properties of an extent.
-
- - Function: extent-face extent
- This function returns the `face' property of EXTENT. This might
- also return a list of face names. Do not modify this list
- directly! Instead, use `set-extent-face'.
-
- Note that you can use `eq' to compare lists of faces as returned
- by `extent-face'. In other words, if you set the face of two
- different extents to two lists that are `equal' but not `eq', then
- the return value of `extent-face' on the two extents will return
- the identical list.
-
- - Function: extent-mouse-face extent
- This function returns the `mouse-face' property of EXTENT. This
- might also return a list of face names. Do not modify this list
- directly! Instead, use `set-extent-mouse-face'.
-
- Note that you can use `eq' to compare lists of faces as returned
- by `extent-mouse-face', just like for `extent-face'.
-
- - Function: extent-priority extent
- This function returns the `priority' property of EXTENT.
-
- - Function: extent-keymap extent
- This function returns the `keymap' property of EXTENT.
-
- - Function: extent-begin-glyph-layout extent
- This function returns the `begin-glyph-layout' property of EXTENT,
- i.e. the layout policy associated with the EXTENT's begin glyph.
-
- - Function: extent-end-glyph-layout extent
- This function returns the `end-glyph-layout' property of EXTENT,
- i.e. the layout policy associated with the EXTENT's end glyph.
-
- - Function: extent-begin-glyph extent
- This function returns the `begin-glyph' property of EXTENT, i.e.
- the glyph object displayed at the beginning of EXTENT. If there
- is none, `nil' is returned.
-
- - Function: extent-end-glyph extent
- This function returns the `end-glyph' property of EXTENT, i.e. the
- glyph object displayed at the end of EXTENT. If there is none,
- `nil' is returned.
-
- The following convenience functions are provided for setting
-particular properties of an extent.
-
- - Function: set-extent-priority extent pri
- This function sets the `priority' property of EXTENT to PRI.
-
- - Function: set-extent-face extent face
- This function sets the `face' property of EXTENT to FACE.
-
- - Function: set-extent-mouse-face extent face
- This function sets the `mouse-face' property of EXTENT to FACE.
-
- - Function: set-extent-keymap extent keymap
- This function sets the `keymap' property of EXTENT to KEYMAP.
- KEYMAP must be either a keymap object, or `nil'.
-
- - Function: set-extent-begin-glyph-layout extent layout
- This function sets the `begin-glyph-layout' property of EXTENT to
- LAYOUT.
-
- - Function: set-extent-end-glyph-layout extent layout
- This function sets the `end-glyph-layout' property of EXTENT to
- LAYOUT.
-
- - Function: set-extent-begin-glyph extent begin-glyph &optional layout
- This function sets the `begin-glyph' and `glyph-layout' properties
- of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
- defaults to `text' if not specified.)
-
- - Function: set-extent-end-glyph extent end-glyph &optional layout
- This function sets the `end-glyph' and `glyph-layout' properties
- of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
- to `text' if not specified.)
-
- - Function: set-extent-initial-redisplay-function extent function
- This function sets the `initial-redisplay-function' property of the
- extent to FUNCTION.
-
-\1f
-File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
-
-Detached Extents
-================
-
- A detached extent is an extent that is not attached to a buffer or
-string but can be re-inserted. Detached extents have a start position
-and end position of `nil'. Extents can be explicitly detached using
-`detach-extent'. An extent is also detached when all of its characters
-are all killed by a deletion, if its `detachable' property is set; if
-this property is not set, the extent becomes a zero-length extent.
-(Zero-length extents with the `detachable' property set behave
-specially. *Note zero-length extents: Extent Endpoints.)
-
- - Function: detach-extent extent
- This function detaches EXTENT from its buffer or string. If
- EXTENT has the `duplicable' property, its detachment is tracked by
- the undo mechanism. *Note Duplicable Extents::.
-
- - Function: extent-detached-p extent
- This function returns `nil' if EXTENT is detached, and `t'
- otherwise.
-
- - Function: copy-extent extent &optional object
- This function makes a copy of EXTENT. It is initially detached.
- Optional argument OBJECT defaults to EXTENT's object (normally a
- buffer or string, but could be `nil').
-
- - Function: insert-extent extent &optional start end no-hooks object
- This function inserts EXTENT from START to END in OBJECT (a buffer
- or string). If EXTENT is detached from a different buffer or
- string, or in most cases when EXTENT is already attached, the
- extent will first be copied as if with `copy-extent'. This
- function operates the same as if `insert' were called on a string
- whose extent data calls for EXTENT to be inserted, except that if
- NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
- invoked. *Note Duplicable Extents::.
-
-\1f
-File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
-
-Extent Parents
-==============
-
- An extent can have a parent extent set for it. If this is the case,
-the extent derives all its properties from that extent and has no
-properties of its own. The only "properties" that the extent keeps are
-the buffer or string it refers to and the start and end points. (More
-correctly, the extent's own properties are shadowed. If you later
-change the extent to have no parent, its own properties will become
-visible again.)
-
- It is possible for an extent's parent to itself have a parent, and
-so on. Through this, a whole tree of extents can be created, all
-deriving their properties from one root extent. Note, however, that
-you cannot create an inheritance loop--this is explicitly disallowed.
-
- Parent extents are used to implement the extents over the modeline.
-
- - Function: set-extent-parent extent parent
- This function sets the parent of EXTENT to PARENT. If PARENT is
- `nil', the extent is set to have no parent.
-
- - Function: extent-parent extent
- This function return the parents (if any) of EXTENT, or `nil'.
-
- - Function: extent-children extent
- This function returns a list of the children (if any) of EXTENT.
- The children of an extent are all those extents whose parent is
- that extent. This function does not recursively trace children of
- children.
-
- - Function: extent-descendants extent
- This function returns a list of all descendants of EXTENT,
- including EXTENT. This recursively applies `extent-children' to
- any children of EXTENT, until no more children can be found.
-
-\1f
-File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
-
-Duplicable Extents
-==================
-
- If an extent has the `duplicable' property, it will be copied into
-strings, so that kill, yank, and undo commands will restore or copy it.
-
- Specifically:
-
- * When a string is created using `buffer-substring' or
- `buffer-string', any duplicable extents in the region corresponding
- to the string will be copied into the string (*note Buffer
- Contents::). When the string in inserted into a buffer using
- `insert', `insert-before-markers', `insert-buffer' or
- `insert-buffer-substring', the extents in the string will be copied
- back into the buffer (*note Insertion::). The extents in a string
- can, of course, be retrieved explicitly using the standard extent
- primitives over the string.
-
- * Similarly, when text is copied or cut into the kill ring, any
- duplicable extents will be remembered and reinserted later when
- the text is pasted back into a buffer.
-
- * When `concat' is called on strings, the extents in the strings are
- copied into the resulting string.
-
- * When `substring' is called on a string, the relevant extents are
- copied into the resulting string.
-
- * When a duplicable extent is detached by `detach-extent' or string
- deletion, or inserted by `insert-extent' or string insertion, the
- action is recorded by the undo mechanism so that it can be undone
- later. Note that if an extent gets detached and then a later undo
- causes the extent to get reinserted, the new extent will not be
- `eq' to the original extent.
-
- * Extent motion, face changes, and attachment via `make-extent' are
- not recorded by the undo mechanism. This means that extent changes
- which are to be undo-able must be performed by character editing,
- or by insertion and detachment of duplicable extents.
-
- * A duplicable extent's `copy-function' property, if non-`nil',
- should be a function, and will be run when a duplicable extent is
- about to be copied from a buffer to a string (or the kill ring).
- It is called with three arguments: the extent and the buffer
- positions within it which are being copied. If this function
- returns `nil', then the extent will not be copied; otherwise it
- will.
-
- * A duplicable extent's `paste-function' property, if non-`nil',
- should be a function, and will be run when a duplicable extent is
- about to be copied from a string (or the kill ring) into a buffer.
- It is called with three arguments: the original extent and the
- buffer positions which the copied extent will occupy. (This hook
- is run after the corresponding text has already been inserted into
- the buffer.) Note that the extent argument may be detached when
- this function is run. If this function returns `nil', no extent
- will be inserted. Otherwise, there will be an extent covering the
- range in question.
-
- Note: if the extent to be copied is already attached to the buffer
- and overlaps the new range, the extent will simply be extended and
- the `paste-function' will not be called.
-
-\1f
-File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
-
-Interaction of Extents with Keyboard and Mouse Events
-=====================================================
-
- If an extent has the `mouse-face' property set, it will be
-highlighted when the mouse passes over it. Highlighting is accomplished
-by merging the extent's face with the face or faces specified by the
-`mouse-face' property. The effect is as if a pseudo-extent with the
-`mouse-face' face were inserted after the extent in the display order
-(*note Extent Endpoints::, display order).
-
- - Variable: mouse-highlight-priority
- This variable holds the priority to use when merging in the
- highlighting pseudo-extent. The default is 1000. This is
- purposely set very high so that the highlighting pseudo-extent
- shows up even if there are other extents with various priorities
- at the same location.
-
- You can also explicitly cause an extent to be highlighted. Only one
-extent at a time can be highlighted in this fashion, and any other
-highlighted extent will be de-highlighted.
-
- - Function: highlight-extent extent &optional highlight-p
- This function highlights (if HIGHLIGHT-P is non-`nil') or
- de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
- `mouse-face' property. (Nothing happens if EXTENT does not have
- the `mouse-face' property.)
-
- - Function: force-highlight-extent extent &optional highlight-p
- This function is similar to `highlight-extent' but highlights or
- de-highlights the extent regardless of whether it has the
- `mouse-face' property.
-
- If an extent has a `keymap' property, this keymap will be consulted
-for mouse clicks on the extent and keypresses made while `point' is
-within the extent. The behavior of mouse clicks and keystrokes not
-defined in the keymap is as normal for the buffer.
-
-\1f
-File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
-
-Atomic Extents
-==============
-
- If the Lisp file `atomic-extents' is loaded, then the atomic extent
-facility is available. An "atomic extent" is an extent for which
-`point' cannot be positioned anywhere within it. This ensures that
-when selecting text, either all or none of the extent is selected.
-
- To make an extent atomic, set its `atomic' property.
-
-\1f
-File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
-
-Specifiers
-**********
-
- A specifier is an object used to keep track of a property whose value
-may vary depending on the particular situation (e.g. particular buffer
-displayed in a particular window) that it is used in. The value of many
-built-in properties, such as the font, foreground, background, and such
-properties of a face and variables such as `modeline-shadow-thickness'
-and `top-toolbar-height', is actually a specifier object. The
-specifier object, in turn, is "instanced" in a particular situation to
-yield the real value of the property in that situation.
-
- - Function: specifierp object
- This function returns non-`nil' if OBJECT is a specifier.
-
-* Menu:
-
-* Introduction to Specifiers:: Specifiers provide a clean way for
- display and other properties to vary
- (under user control) in a wide variety
- of contexts.
-* Specifiers In-Depth:: Gory details about specifier innards.
-* Specifier Instancing:: Instancing means obtaining the ``value'' of
- a specifier in a particular context.
-* Specifier Types:: Specifiers come in different flavors.
-* Adding Specifications:: Specifications control a specifier's ``value''
- by giving conditions under which a
- particular value is valid.
-* Retrieving Specifications:: Querying a specifier's specifications.
-* Specifier Tag Functions:: Working with specifier tags.
-* Specifier Instancing Functions::
- Functions to instance a specifier.
-* Specifier Example:: Making all this stuff clearer.
-* Creating Specifiers:: Creating specifiers for your own use.
-* Specifier Validation Functions::
- Validating the components of a specifier.
-* Other Specification Functions::
- Other ways of working with specifications.
-
-\1f
-File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers
-
-Introduction to Specifiers
-==========================
-
- Sometimes you may want the value of a property to vary depending on
-the context the property is used in. A simple example of this in XEmacs
-is buffer-local variables. For example, the variable
-`modeline-format', which controls the format of the modeline, can have
-different values depending on the particular buffer being edited. The
-variable has a default value which most modes will use, but a
-specialized package such as Calendar might change the variable so as to
-tailor the modeline to its own purposes.
-
- Other properties (such as those that can be changed by the
-`modify-frame-parameters' function, for example the color of the text
-cursor) can have frame-local values, although it might also make sense
-for them to have buffer-local values. In other cases, you might want
-the property to vary depending on the particular window within the
-frame that applies (e.g. the top or bottom window in a split frame), the
-device type that that frame appears on (X or tty), etc. Perhaps you can
-envision some more complicated scenario where you want a particular
-value in a specified buffer, another value in all other buffers
-displayed on a particular frame, another value in all other buffers
-displayed in all other frames on any mono (two-color, e.g. black and
-white only) displays, and a default value in all other circumstances.
-
- A "specifier" is a generalization of this, allowing a great deal of
-flexibility in controlling exactly what value a property has in which
-circumstances. It is most commonly used for display properties, such as
-an image or the foreground color of a face. As a simple example, you
-can specify that the foreground of the default face be
-
- * blue for a particular buffer
-
- * green for all other buffers
-
- As a more complicated example, you could specify that the foreground
-of the default face be
-
- * forest green for all buffers displayed in a particular Emacs
- window, or green if the X server doesn't recognize the color
- `forest green'
-
- * blue for all buffers displayed in a particular frame
-
- * red for all other buffers displayed on a color device
-
- * white for all other buffers
-
-\1f
-File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers
-
-In-Depth Overview of a Specifier
-================================
-
- A specifier object encapsulates a set of "specifications", each of
-which says what its value should be if a particular condition applies.
-For example, one specification might be "The value should be
-darkseagreen2 on X devices" another might be "The value should be blue
-in the *Help* buffer". In specifier terminology, these conditions are
-called "locales" and the values are called "instantiators". Given a
-specifier, a logical question is "What is its value in a particular
-situation?" This involves looking through the specifications to see
-which ones apply to this particular situation, and perhaps preferring
-one over another if more than one applies. In specifier terminology, a
-"particular situation" is called a "domain", and determining its value
-in a particular domain is called "instancing". Most of the time, a
-domain is identified by a particular window. For example, if the
-redisplay engine is drawing text in the default face in a particular
-window, it retrieves the specifier for the foreground color of the
-default face and "instances" it in the domain given by that window; in
-other words, it asks the specifier, "What is your value in this
-window?".
-
- More specifically, a specifier contains a set of "specifications",
-each of which associates a "locale" (a window object, a buffer object,
-a frame object, a device object, or the symbol `global') with an
-"inst-list", which is a list of one or more "inst-pairs". (For each
-possible locale, there can be at most one specification containing that
-locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
-zero or more symbols, or "tags") and an "instantiator" (the allowed
-form of this varies depending on the type of specifier). In a given
-specification, there may be more than one inst-pair with the same tag
-set; this is unlike for locales.
-
- The tag set is used to restrict the sorts of devices over which the
-instantiator is valid and to uniquely identify instantiators added by a
-particular application, so that different applications can work on the
-same specifier and not interfere with each other. Each tag can have a
-"predicate" associated with it, which is a function of one argument (a
-device) that specifies whether the tag matches that particular device.
-(If a tag does not have a predicate, it matches all devices.) All tags
-in a tag set must match a device for the associated inst-pair to be
-instantiable over that device. (A null tag set is perfectly valid.)
-
- The valid device types (normally `x', `tty', and `stream') and
-device classes (normally `color', `grayscale', and `mono') can always
-be used as tags, and match devices of the associated type or class
-(*note Consoles and Devices::). User-defined tags may be defined, with
-an optional predicate specified. An application can create its own
-tag, use it to mark all its instantiators, and be fairly confident that
-it will not interfere with other applications that modify the same
-specifier--Functions that add a specification to a specifier usually
-only overwrite existing inst-pairs with the same tag set as was given,
-and a particular tag or tag set can be specified when removing
-instantiators.
-
- When a specifier is instanced in a domain, both the locale and the
-tag set can be viewed as specifying necessary conditions that must
-apply in that domain for an instantiator to be considered as a possible
-result of the instancing. More specific locales always override more
-general locales (thus, there is no particular ordering of the
-specifications in a specifier); however, the tag sets are simply
-considered in the order that the inst-pairs occur in the
-specification's inst-list.
-
- Note also that the actual object that results from the instancing
-(called an "instance object") may not be the same as the instantiator
-from which it was derived. For some specifier types (such as integer
-specifiers and boolean specifiers), the instantiator will be returned
-directly as the instance object. For other types, however, this is not
-the case. For example, for font specifiers, the instantiator is a
-font-description string and the instance object is a font-instance
-object, which describes how the font is displayed on a particular
-device. A font-instance object encapsulates such things as the actual
-font name used to display the font on that device (a font-description
-string under X is usually a wildcard specification that may resolve to
-different font names, with possibly different foundries, widths, etc.,
-on different devices), the extra properties of that font on that
-device, etc. Furthermore, this conversion (called "instantiation")
-might fail--a font or color might not exist on a particular device, for
-example.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
+
+Properties of Extents
+=====================
+
+ Each extent has a property list associating property names with
+values. Some property names have predefined meanings, and can usually
+only assume particular values. Assigning other values to such a
+property either cause the value to be converted into a legal value
+(e.g., assigning anything but `nil' to a Boolean property will cause
+the value of `t' to be assigned to the property) or will cause an
+error. Property names without predefined meanings can be assigned any
+value. An undefined property is equivalent to a property with a value
+of `nil', or with a particular default value in the case of properties
+with predefined meanings. Note that, when an extent is created, the
+`end-open' and `detachable' properties are set on it.
+
+ If an extent has a parent, all of its properties actually derive
+from that parent (or from the root ancestor if the parent in turn has a
+parent), and setting a property of the extent actually sets that
+property on the parent. *Note Extent Parents::.
+
+ - Function: extent-property extent property
+ This function returns the value of PROPERTY in EXTENT. If
+ PROPERTY is undefined, `nil' is returned.
+
+ - Function: extent-properties extent
+ This function returns a list of all of EXTENT's properties that do
+ not have the value of `nil' (or the default value, for properties
+ with predefined meanings).
+
+ - Function: set-extent-property extent property value
+ This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
+ predefined meaning, only certain values are allowed, and some
+ values may be converted to others before being stored.)
+
+ - Function: set-extent-properties extent plist
+ Change some properties of EXTENT. PLIST is a property list. This
+ is useful to change many extent properties at once.
+
+ The following table lists the properties with predefined meanings,
+along with their allowable values.
+
+`detached'
+ (Boolean) Whether the extent is detached. Setting this is the
+ same as calling `detach-extent'. *Note Detached Extents::.
+
+`destroyed'
+ (Boolean) Whether the extent has been deleted. Setting this is
+ the same as calling `delete-extent'.
+
+`priority'
+ (integer) The extent's redisplay priority. Defaults to 0. *Note
+ priority: Intro to Extents. This property can also be set with
+ `set-extent-priority' and accessed with `extent-priority'.
+
+`start-open'
+ (Boolean) Whether the start position of the extent is open,
+ meaning that characters inserted at that position go outside of
+ the extent. *Note Extent Endpoints::.
+
+`start-closed'
+ (Boolean) Same as `start-open' but with the opposite sense.
+ Setting this property clears `start-open' and vice-versa.
+
+`end-open'
+ (Boolean) Whether the end position of the extent is open, meaning
+ that characters inserted at that position go outside of the
+ extent. This is `t' by default. *Note Extent Endpoints::.
+
+`end-closed'
+ (Boolean) Same as `end-open' but with the opposite sense. Setting
+ this property clears `end-open' and vice-versa.
+
+`read-only'
+ (Boolean) Whether text within this extent will be unmodifiable.
+
+`face'
+ (face, face name, list of faces or face names, or `nil') The face
+ in which to display the extent's text. This property can also be
+ set with `set-extent-face' and accessed with `extent-face'. Note
+ that if a list of faces is specified, the faces are merged
+ together, with faces earlier in the list having priority over
+ faces later in the list.
+
+`mouse-face'
+ (face, face name, list of faces or face names, or `nil') The face
+ used to display the extent when the mouse moves over it. This
+ property can also be set with `set-extent-mouse-face' and accessed
+ with `extent-mouse-face'. Note that if a list of faces is
+ specified, the faces are merged together, with faces earlier in
+ the list having priority over faces later in the list. *Note
+ Extents and Events::.
+
+`pointer'
+ (pointer glyph) The glyph used as the pointer when the mouse
+ moves over the extent. This takes precedence over the
+ `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
+ for any reason this glyph is an invalid pointer, the standard
+ glyphs will be used as fallbacks. *Note Mouse Pointer::.
+
+`detachable'
+ (Boolean) Whether this extent becomes detached when all of the
+ text it covers is deleted. This is `t' by default. *Note
+ Detached Extents::.
+
+`duplicable'
+ (Boolean) Whether this extent should be copied into strings, so
+ that kill, yank, and undo commands will restore or copy it. *Note
+ Duplicable Extents::.
+
+`unique'
+ (Boolean) Meaningful only in conjunction with `duplicable'. When
+ this is set, there may be only one instance of this extent
+ attached at a time. *Note Duplicable Extents::.
+
+`invisible'
+ (Boolean) If `t', text under this extent will not be displayed -
+ it will look as if the text is not there at all.
+
+`keymap'
+ (keymap or `nil') This keymap is consulted for mouse clicks on this
+ extent or keypresses made while `point' is within the extent.
+ *Note Extents and Events::.
+
+`copy-function'
+ This is a hook that is run when a duplicable extent is about to be
+ copied from a buffer to a string (or the kill ring). *Note
+ Duplicable Extents::.
+
+`paste-function'
+ This is a hook that is run when a duplicable extent is about to be
+ copied from a string (or the kill ring) into a buffer. *Note
+ Duplicable Extents::.
+
+`begin-glyph'
+ (glyph or `nil') This extent's begin glyph. *Note Annotations::.
+
+`end-glyph'
+ (glyph or `nil') This extent's end glyph. *Note Annotations::.
+
+`begin-glyph-layout'
+ (`text', `whitespace', `inside-margin', or `outside-margin') The
+ layout policy for this extent's begin glyph. Defaults to `text'.
+ *Note Annotations::.
+
+`end-glyph-layout'
+ (`text', `whitespace', `inside-margin', or `outside-margin') The
+ layout policy for this extent's end glyph. Defaults to `text'.
+ *Note Annotations::.
+
+`initial-redisplay-function'
+ (any funcallable object) The function to be called the first time
+ (a part of) the extent is redisplayed. It will be called with the
+ extent as its argument.
+
+ This is used by `lazy-shot' to implement lazy font-locking. The
+ functionality is still experimental, and may change without further
+ notice.
+
+ The following convenience functions are provided for accessing
+particular properties of an extent.
+
+ - Function: extent-face extent
+ This function returns the `face' property of EXTENT. This might
+ also return a list of face names. Do not modify this list
+ directly! Instead, use `set-extent-face'.
+
+ Note that you can use `eq' to compare lists of faces as returned
+ by `extent-face'. In other words, if you set the face of two
+ different extents to two lists that are `equal' but not `eq', then
+ the return value of `extent-face' on the two extents will return
+ the identical list.
+
+ - Function: extent-mouse-face extent
+ This function returns the `mouse-face' property of EXTENT. This
+ might also return a list of face names. Do not modify this list
+ directly! Instead, use `set-extent-mouse-face'.
+
+ Note that you can use `eq' to compare lists of faces as returned
+ by `extent-mouse-face', just like for `extent-face'.
+
+ - Function: extent-priority extent
+ This function returns the `priority' property of EXTENT.
+
+ - Function: extent-keymap extent
+ This function returns the `keymap' property of EXTENT.
+
+ - Function: extent-begin-glyph-layout extent
+ This function returns the `begin-glyph-layout' property of EXTENT,
+ i.e. the layout policy associated with the EXTENT's begin glyph.
+
+ - Function: extent-end-glyph-layout extent
+ This function returns the `end-glyph-layout' property of EXTENT,
+ i.e. the layout policy associated with the EXTENT's end glyph.
+
+ - Function: extent-begin-glyph extent
+ This function returns the `begin-glyph' property of EXTENT, i.e.
+ the glyph object displayed at the beginning of EXTENT. If there
+ is none, `nil' is returned.
+
+ - Function: extent-end-glyph extent
+ This function returns the `end-glyph' property of EXTENT, i.e. the
+ glyph object displayed at the end of EXTENT. If there is none,
+ `nil' is returned.
+
+ The following convenience functions are provided for setting
+particular properties of an extent.
+
+ - Function: set-extent-priority extent pri
+ This function sets the `priority' property of EXTENT to PRI.
+
+ - Function: set-extent-face extent face
+ This function sets the `face' property of EXTENT to FACE.
+
+ - Function: set-extent-mouse-face extent face
+ This function sets the `mouse-face' property of EXTENT to FACE.
+
+ - Function: set-extent-keymap extent keymap
+ This function sets the `keymap' property of EXTENT to KEYMAP.
+ KEYMAP must be either a keymap object, or `nil'.
+
+ - Function: set-extent-begin-glyph-layout extent layout
+ This function sets the `begin-glyph-layout' property of EXTENT to
+ LAYOUT.
+
+ - Function: set-extent-end-glyph-layout extent layout
+ This function sets the `end-glyph-layout' property of EXTENT to
+ LAYOUT.
+
+ - Function: set-extent-begin-glyph extent begin-glyph &optional layout
+ This function sets the `begin-glyph' and `glyph-layout' properties
+ of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
+ defaults to `text' if not specified.)
+
+ - Function: set-extent-end-glyph extent end-glyph &optional layout
+ This function sets the `end-glyph' and `glyph-layout' properties
+ of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
+ to `text' if not specified.)
+
+ - Function: set-extent-initial-redisplay-function extent function
+ This function sets the `initial-redisplay-function' property of the
+ extent to FUNCTION.
+
+\1f
+File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
+
+Detached Extents
+================
+
+ A detached extent is an extent that is not attached to a buffer or
+string but can be re-inserted. Detached extents have a start position
+and end position of `nil'. Extents can be explicitly detached using
+`detach-extent'. An extent is also detached when all of its characters
+are all killed by a deletion, if its `detachable' property is set; if
+this property is not set, the extent becomes a zero-length extent.
+(Zero-length extents with the `detachable' property set behave
+specially. *Note zero-length extents: Extent Endpoints.)
+
+ - Function: detach-extent extent
+ This function detaches EXTENT from its buffer or string. If
+ EXTENT has the `duplicable' property, its detachment is tracked by
+ the undo mechanism. *Note Duplicable Extents::.
+
+ - Function: extent-detached-p extent
+ This function returns `nil' if EXTENT is detached, and `t'
+ otherwise.
+
+ - Function: copy-extent extent &optional object
+ This function makes a copy of EXTENT. It is initially detached.
+ Optional argument OBJECT defaults to EXTENT's object (normally a
+ buffer or string, but could be `nil').
+
+ - Function: insert-extent extent &optional start end no-hooks object
+ This function inserts EXTENT from START to END in OBJECT (a buffer
+ or string). If EXTENT is detached from a different buffer or
+ string, or in most cases when EXTENT is already attached, the
+ extent will first be copied as if with `copy-extent'. This
+ function operates the same as if `insert' were called on a string
+ whose extent data calls for EXTENT to be inserted, except that if
+ NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
+ invoked. *Note Duplicable Extents::.
+
+\1f
+File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
+
+Extent Parents
+==============
+
+ An extent can have a parent extent set for it. If this is the case,
+the extent derives all its properties from that extent and has no
+properties of its own. The only "properties" that the extent keeps are
+the buffer or string it refers to and the start and end points. (More
+correctly, the extent's own properties are shadowed. If you later
+change the extent to have no parent, its own properties will become
+visible again.)
+
+ It is possible for an extent's parent to itself have a parent, and
+so on. Through this, a whole tree of extents can be created, all
+deriving their properties from one root extent. Note, however, that
+you cannot create an inheritance loop--this is explicitly disallowed.
+
+ Parent extents are used to implement the extents over the modeline.
+
+ - Function: set-extent-parent extent parent
+ This function sets the parent of EXTENT to PARENT. If PARENT is
+ `nil', the extent is set to have no parent.
+
+ - Function: extent-parent extent
+ This function return the parents (if any) of EXTENT, or `nil'.
+
+ - Function: extent-children extent
+ This function returns a list of the children (if any) of EXTENT.
+ The children of an extent are all those extents whose parent is
+ that extent. This function does not recursively trace children of
+ children.
+
+ - Function: extent-descendants extent
+ This function returns a list of all descendants of EXTENT,
+ including EXTENT. This recursively applies `extent-children' to
+ any children of EXTENT, until no more children can be found.
+
+\1f
+File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
+
+Duplicable Extents
+==================
+
+ If an extent has the `duplicable' property, it will be copied into
+strings, so that kill, yank, and undo commands will restore or copy it.
+
+ Specifically:
+
+ * When a string is created using `buffer-substring' or
+ `buffer-string', any duplicable extents in the region corresponding
+ to the string will be copied into the string (*note Buffer
+ Contents::). When the string in inserted into a buffer using
+ `insert', `insert-before-markers', `insert-buffer' or
+ `insert-buffer-substring', the extents in the string will be copied
+ back into the buffer (*note Insertion::). The extents in a string
+ can, of course, be retrieved explicitly using the standard extent
+ primitives over the string.
+
+ * Similarly, when text is copied or cut into the kill ring, any
+ duplicable extents will be remembered and reinserted later when
+ the text is pasted back into a buffer.
+
+ * When `concat' is called on strings, the extents in the strings are
+ copied into the resulting string.
+
+ * When `substring' is called on a string, the relevant extents are
+ copied into the resulting string.
+
+ * When a duplicable extent is detached by `detach-extent' or string
+ deletion, or inserted by `insert-extent' or string insertion, the
+ action is recorded by the undo mechanism so that it can be undone
+ later. Note that if an extent gets detached and then a later undo
+ causes the extent to get reinserted, the new extent will not be
+ `eq' to the original extent.
+
+ * Extent motion, face changes, and attachment via `make-extent' are
+ not recorded by the undo mechanism. This means that extent changes
+ which are to be undo-able must be performed by character editing,
+ or by insertion and detachment of duplicable extents.
+
+ * A duplicable extent's `copy-function' property, if non-`nil',
+ should be a function, and will be run when a duplicable extent is
+ about to be copied from a buffer to a string (or the kill ring).
+ It is called with three arguments: the extent and the buffer
+ positions within it which are being copied. If this function
+ returns `nil', then the extent will not be copied; otherwise it
+ will.
+
+ * A duplicable extent's `paste-function' property, if non-`nil',
+ should be a function, and will be run when a duplicable extent is
+ about to be copied from a string (or the kill ring) into a buffer.
+ It is called with three arguments: the original extent and the
+ buffer positions which the copied extent will occupy. (This hook
+ is run after the corresponding text has already been inserted into
+ the buffer.) Note that the extent argument may be detached when
+ this function is run. If this function returns `nil', no extent
+ will be inserted. Otherwise, there will be an extent covering the
+ range in question.
+
+ Note: if the extent to be copied is already attached to the buffer
+ and overlaps the new range, the extent will simply be extended and
+ the `paste-function' will not be called.
+
+\1f
+File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
+
+Interaction of Extents with Keyboard and Mouse Events
+=====================================================
+
+ If an extent has the `mouse-face' property set, it will be
+highlighted when the mouse passes over it. Highlighting is accomplished
+by merging the extent's face with the face or faces specified by the
+`mouse-face' property. The effect is as if a pseudo-extent with the
+`mouse-face' face were inserted after the extent in the display order
+(*note Extent Endpoints::, display order).
+
+ - Variable: mouse-highlight-priority
+ This variable holds the priority to use when merging in the
+ highlighting pseudo-extent. The default is 1000. This is
+ purposely set very high so that the highlighting pseudo-extent
+ shows up even if there are other extents with various priorities
+ at the same location.
+
+ You can also explicitly cause an extent to be highlighted. Only one
+extent at a time can be highlighted in this fashion, and any other
+highlighted extent will be de-highlighted.
+
+ - Function: highlight-extent extent &optional highlight-p
+ This function highlights (if HIGHLIGHT-P is non-`nil') or
+ de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
+ `mouse-face' property. (Nothing happens if EXTENT does not have
+ the `mouse-face' property.)
+
+ - Function: force-highlight-extent extent &optional highlight-p
+ This function is similar to `highlight-extent' but highlights or
+ de-highlights the extent regardless of whether it has the
+ `mouse-face' property.
+
+ If an extent has a `keymap' property, this keymap will be consulted
+for mouse clicks on the extent and keypresses made while `point' is
+within the extent. The behavior of mouse clicks and keystrokes not
+defined in the keymap is as normal for the buffer.
+
+\1f
+File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
+
+Atomic Extents
+==============
+
+ If the Lisp file `atomic-extents' is loaded, then the atomic extent
+facility is available. An "atomic extent" is an extent for which
+`point' cannot be positioned anywhere within it. This ensures that
+when selecting text, either all or none of the extent is selected.
+
+ To make an extent atomic, set its `atomic' property.
+
+\1f
+File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
+
+Specifiers
+**********
+
+ A specifier is an object used to keep track of a property whose value
+may vary depending on the particular situation (e.g. particular buffer
+displayed in a particular window) that it is used in. The value of many
+built-in properties, such as the font, foreground, background, and such
+properties of a face and variables such as `modeline-shadow-thickness'
+and `top-toolbar-height', is actually a specifier object. The
+specifier object, in turn, is "instanced" in a particular situation to
+yield the real value of the property in that situation.
+
+ - Function: specifierp object
+ This function returns non-`nil' if OBJECT is a specifier.
+
+* Menu:
+
+* Introduction to Specifiers:: Specifiers provide a clean way for
+ display and other properties to vary
+ (under user control) in a wide variety
+ of contexts.
+* Specifiers In-Depth:: Gory details about specifier innards.
+* Specifier Instancing:: Instancing means obtaining the ``value'' of
+ a specifier in a particular context.
+* Specifier Types:: Specifiers come in different flavors.
+* Adding Specifications:: Specifications control a specifier's ``value''
+ by giving conditions under which a
+ particular value is valid.
+* Retrieving Specifications:: Querying a specifier's specifications.
+* Specifier Tag Functions:: Working with specifier tags.
+* Specifier Instancing Functions::
+ Functions to instance a specifier.
+* Specifier Example:: Making all this stuff clearer.
+* Creating Specifiers:: Creating specifiers for your own use.
+* Specifier Validation Functions::
+ Validating the components of a specifier.
+* Other Specification Functions::
+ Other ways of working with specifications.
+
+\1f
+File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers
+
+Introduction to Specifiers
+==========================
+
+ Sometimes you may want the value of a property to vary depending on
+the context the property is used in. A simple example of this in XEmacs
+is buffer-local variables. For example, the variable
+`modeline-format', which controls the format of the modeline, can have
+different values depending on the particular buffer being edited. The
+variable has a default value which most modes will use, but a
+specialized package such as Calendar might change the variable so as to
+tailor the modeline to its own purposes.
+
+ Other properties (such as those that can be changed by the
+`modify-frame-parameters' function, for example the color of the text
+cursor) can have frame-local values, although it might also make sense
+for them to have buffer-local values. In other cases, you might want
+the property to vary depending on the particular window within the
+frame that applies (e.g. the top or bottom window in a split frame), the
+device type that that frame appears on (X or tty), etc. Perhaps you can
+envision some more complicated scenario where you want a particular
+value in a specified buffer, another value in all other buffers
+displayed on a particular frame, another value in all other buffers
+displayed in all other frames on any mono (two-color, e.g. black and
+white only) displays, and a default value in all other circumstances.
+
+ A "specifier" is a generalization of this, allowing a great deal of
+flexibility in controlling exactly what value a property has in which
+circumstances. It is most commonly used for display properties, such as
+an image or the foreground color of a face. As a simple example, you
+can specify that the foreground of the default face be
+
+ * blue for a particular buffer
+
+ * green for all other buffers
+
+ As a more complicated example, you could specify that the foreground
+of the default face be
+
+ * forest green for all buffers displayed in a particular Emacs
+ window, or green if the X server doesn't recognize the color
+ `forest green'
+
+ * blue for all buffers displayed in a particular frame
+
+ * red for all other buffers displayed on a color device
+
+ * white for all other buffers
+
+\1f
+File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers
+
+In-Depth Overview of a Specifier
+================================
+
+ A specifier object encapsulates a set of "specifications", each of
+which says what its value should be if a particular condition applies.
+For example, one specification might be "The value should be
+darkseagreen2 on X devices" another might be "The value should be blue
+in the *Help* buffer". In specifier terminology, these conditions are
+called "locales" and the values are called "instantiators". Given a
+specifier, a logical question is "What is its value in a particular
+situation?" This involves looking through the specifications to see
+which ones apply to this particular situation, and perhaps preferring
+one over another if more than one applies. In specifier terminology, a
+"particular situation" is called a "domain", and determining its value
+in a particular domain is called "instancing". Most of the time, a
+domain is identified by a particular window. For example, if the
+redisplay engine is drawing text in the default face in a particular
+window, it retrieves the specifier for the foreground color of the
+default face and "instances" it in the domain given by that window; in
+other words, it asks the specifier, "What is your value in this
+window?".
+
+ More specifically, a specifier contains a set of "specifications",
+each of which associates a "locale" (a window object, a buffer object,
+a frame object, a device object, or the symbol `global') with an
+"inst-list", which is a list of one or more "inst-pairs". (For each
+possible locale, there can be at most one specification containing that
+locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
+zero or more symbols, or "tags") and an "instantiator" (the allowed
+form of this varies depending on the type of specifier). In a given
+specification, there may be more than one inst-pair with the same tag
+set; this is unlike for locales.
+
+ The tag set is used to restrict the sorts of devices over which the
+instantiator is valid and to uniquely identify instantiators added by a
+particular application, so that different applications can work on the
+same specifier and not interfere with each other. Each tag can have a
+"predicate" associated with it, which is a function of one argument (a
+device) that specifies whether the tag matches that particular device.
+(If a tag does not have a predicate, it matches all devices.) All tags
+in a tag set must match a device for the associated inst-pair to be
+instantiable over that device. (A null tag set is perfectly valid.)
+
+ The valid device types (normally `x', `tty', and `stream') and
+device classes (normally `color', `grayscale', and `mono') can always
+be used as tags, and match devices of the associated type or class
+(*note Consoles and Devices::). User-defined tags may be defined, with
+an optional predicate specified. An application can create its own
+tag, use it to mark all its instantiators, and be fairly confident that
+it will not interfere with other applications that modify the same
+specifier--Functions that add a specification to a specifier usually
+only overwrite existing inst-pairs with the same tag set as was given,
+and a particular tag or tag set can be specified when removing
+instantiators.
+
+ When a specifier is instanced in a domain, both the locale and the
+tag set can be viewed as specifying necessary conditions that must
+apply in that domain for an instantiator to be considered as a possible
+result of the instancing. More specific locales always override more
+general locales (thus, there is no particular ordering of the
+specifications in a specifier); however, the tag sets are simply
+considered in the order that the inst-pairs occur in the
+specification's inst-list.
+
+ Note also that the actual object that results from the instancing
+(called an "instance object") may not be the same as the instantiator
+from which it was derived. For some specifier types (such as integer
+specifiers and boolean specifiers), the instantiator will be returned
+directly as the instance object. For other types, however, this is not
+the case. For example, for font specifiers, the instantiator is a
+font-description string and the instance object is a font-instance
+object, which describes how the font is displayed on a particular
+device. A font-instance object encapsulates such things as the actual
+font name used to display the font on that device (a font-description
+string under X is usually a wildcard specification that may resolve to
+different font names, with possibly different foundries, widths, etc.,
+on different devices), the extra properties of that font on that
+device, etc. Furthermore, this conversion (called "instantiation")
+might fail--a font or color might not exist on a particular device, for
+example.
+
+\1f
File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers
How a Specifier Is Instanced
If NOERROR is `nil', signal an error if the spec-list is invalid;
otherwise return `t'.
-\1f
-File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
-
-Retrieving the Specifications from a Specifier
-==============================================
-
- - Function: specifier-spec-list specifier &optional locale tag-set
- exact-p
- This function returns the spec-list of specifications for
- SPECIFIER in LOCALE.
-
- If LOCALE is a particular locale (a window, buffer, frame, device,
- or the symbol `global'), a spec-list consisting of the
- specification for that locale will be returned.
-
- If LOCALE is a locale type (i.e. a symbol `window', `buffer',
- `frame', or `device'), a spec-list of the specifications for all
- locales of that type will be returned.
-
- If LOCALE is `nil' or the symbol `all', a spec-list of all
- specifications in SPECIFIER will be returned.
-
- LOCALE can also be a list of locales, locale types, and/or `all';
- the result is as if `specifier-spec-list' were called on each
- element of the list and the results concatenated together.
-
- Only instantiators where TAG-SET (a list of zero or more tags) is
- a subset of (or possibly equal to) the instantiator's tag set are
- returned. (The default value of` nil' is a subset of all tag sets,
- so in this case no instantiators will be screened out.) If EXACT-P
- is non-`nil', however, TAG-SET must be equal to an instantiator's
- tag set for the instantiator to be returned.
-
- - Function: specifier-specs specifier &optional locale tag-set exact-p
- This function returns the specification(s) for SPECIFIER in LOCALE.
-
- If LOCALE is a single locale or is a list of one element
- containing a single locale, then a "short form" of the
- instantiators for that locale will be returned. Otherwise, this
- function is identical to `specifier-spec-list'.
-
- The "short form" is designed for readability and not for ease of
- use in Lisp programs, and is as follows:
-
- 1. If there is only one instantiator, then an inst-pair (i.e.
- cons of tag and instantiator) will be returned; otherwise a
- list of inst-pairs will be returned.
-
- 2. For each inst-pair returned, if the instantiator's tag is
- `any', the tag will be removed and the instantiator itself
- will be returned instead of the inst-pair.
-
- 3. If there is only one instantiator, its value is `nil', and
- its tag is `any', a one-element list containing `nil' will be
- returned rather than just `nil', to distinguish this case
- from there being no instantiators at all.
-
-
- - Function: specifier-fallback specifier
- This function returns the fallback value for SPECIFIER. Fallback
- values are provided by the C code for certain built-in specifiers
- to make sure that instancing won't fail even if all specs are
- removed from the specifier, or to implement simple inheritance
- behavior (e.g. this method is used to ensure that faces other than
- `default' inherit their attributes from `default'). By design,
- you cannot change the fallback value, and specifiers created with
- `make-specifier' will never have a fallback (although a similar,
- Lisp-accessible capability may be provided in the future to allow
- for inheritance).
-
- The fallback value will be an inst-list that is instanced like any
- other inst-list, a specifier of the same type as SPECIFIER
- (results in inheritance), or `nil' for no fallback.
-
- When you instance a specifier, you can explicitly request that the
- fallback not be consulted. (The C code does this, for example, when
- merging faces.) See `specifier-instance'.
-
-\1f
-File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
-
-Working With Specifier Tags
-===========================
-
- A specifier tag set is an entity that is attached to an instantiator
-and can be used to restrict the scope of that instantiator to a
-particular device class or device type and/or to mark instantiators
-added by a particular package so that they can be later removed.
-
- A specifier tag set consists of a list of zero of more specifier
-tags, each of which is a symbol that is recognized by XEmacs as a tag.
-(The valid device types and device classes are always tags, as are any
-tags defined by `define-specifier-tag'.) It is called a "tag set" (as
-opposed to a list) because the order of the tags or the number of times
-a particular tag occurs does not matter.
-
- Each tag has a predicate associated with it, which specifies whether
-that tag applies to a particular device. The tags which are device
-types and classes match devices of that type or class. User-defined
-tags can have any predicate, or none (meaning that all devices match).
-When attempting to instance a specifier, a particular instantiator is
-only considered if the device of the domain being instanced over matches
-all tags in the tag set attached to that instantiator.
-
- Most of the time, a tag set is not specified, and the instantiator
-gets a null tag set, which matches all devices.
-
- - Function: valid-specifier-tag-p tag
- This function returns non-`nil' if TAG is a valid specifier tag.
-
- - Function: valid-specifier-tag-set-p tag-set
- This function returns non-`nil' if TAG-SET is a valid specifier
- tag set.
-
- - Function: canonicalize-tag-set tag-set
- This function canonicalizes the given tag set. Two canonicalized
- tag sets can be compared with `equal' to see if they represent the
- same tag set. (Specifically, canonicalizing involves sorting by
- symbol name and removing duplicates.)
-
- - Function: device-matches-specifier-tag-set-p device tag-set
- This function returns non-`nil' if DEVICE matches specifier tag
- set TAG-SET. This means that DEVICE matches each tag in the tag
- set.
-
- - Function: define-specifier-tag tag &optional predicate
- This function defines a new specifier tag. If PREDICATE is
- specified, it should be a function of one argument (a device) that
- specifies whether the tag matches that particular device. If
- PREDICATE is omitted, the tag matches all devices.
-
- You can redefine an existing user-defined specifier tag. However,
- you cannot redefine the built-in specifier tags (the device types
- and classes) or the symbols `nil', `t', `all', or `global'.
-
- - Function: device-matching-specifier-tag-list &optional device
- This function returns a list of all specifier tags matching
- DEVICE. DEVICE defaults to the selected device if omitted.
-
- - Function: specifier-tag-list
- This function returns a list of all currently-defined specifier
- tags. This includes the built-in ones (the device types and
- classes).
-
- - Function: specifier-tag-predicate tag
- This function returns the predicate for the given specifier tag.
-
-\1f
-File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers
-
-Functions for Instancing a Specifier
-====================================
-
- - Function: specifier-instance specifier &optional domain default
- no-fallback
- This function instantiates SPECIFIER (return its value) in DOMAIN.
- If no instance can be generated for this domain, return DEFAULT.
-
- DOMAIN should be a window, frame, or device. Other values that
- are legal as a locale (e.g. a buffer) are not valid as a domain
- because they do not provide enough information to identify a
- particular device (see `valid-specifier-domain-p'). DOMAIN
- defaults to the selected window if omitted.
-
- "Instantiating" a specifier in a particular domain means
- determining the specifier's "value" in that domain. This is
- accomplished by searching through the specifications in the
- specifier that correspond to all locales that can be derived from
- the given domain, from specific to general. In most cases, the
- domain is an Emacs window. In that case specifications are
- searched for as follows:
-
- 1. A specification whose locale is the window itself;
-
- 2. A specification whose locale is the window's buffer;
-
- 3. A specification whose locale is the window's frame;
-
- 4. A specification whose locale is the window's frame's device;
-
- 5. A specification whose locale is the symbol `global'.
-
- If all of those fail, then the C-code-provided fallback value for
- this specifier is consulted (see `specifier-fallback'). If it is
- an inst-list, then this function attempts to instantiate that list
- just as when a specification is located in the first five steps
- above. If the fallback is a specifier, `specifier-instance' is
- called recursively on this specifier and the return value used.
- Note, however, that if the optional argument NO-FALLBACK is
- non-`nil', the fallback value will not be consulted.
-
- Note that there may be more than one specification matching a
- particular locale; all such specifications are considered before
- looking for any specifications for more general locales. Any
- particular specification that is found may be rejected because it
- is tagged to a particular device class (e.g. `color') or device
- type (e.g. `x') or both and the device for the given domain does
- not match this, or because the specification is not valid for the
- device of the given domain (e.g. the font or color name does not
- exist for this particular X server).
-
- The returned value is dependent on the type of specifier. For
- example, for a font specifier (as returned by the `face-font'
- function), the returned value will be a font-instance object. For
- images, the returned value will be a string, pixmap, or subwindow.
-
- - Function: specifier-instance-from-inst-list specifier domain
- inst-list &optional default
- This function attempts to convert a particular inst-list into an
- instance. This attempts to instantiate INST-LIST in the given
- DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
- If the instantiation fails, DEFAULT is returned. In most
- circumstances, you should not use this function; use
- `specifier-instance' instead.
-
-\1f
-File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
-
-Example of Specifier Usage
-==========================
-
- Now let us present an example to clarify the theoretical discussions
-we have been through. In this example, we will use the general
-specifier functions for clarity. Keep in mind that many types of
-specifiers, and some other types of objects that are associated with
-specifiers (e.g. faces), provide convenience functions making it easier
-to work with objects of that type.
-
- Let us consider the background color of the default face. A
-specifier is used to specify how that color will appear in different
-domains. First, let's retrieve the specifier:
-
- (setq sp (face-property 'default 'background))
- => #<color-specifier 0x3da>
-
- (specifier-specs sp)
- => ((#<buffer "device.c"> (nil . "forest green"))
- (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
- (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
- (nil . "moccasin"))
- (#<x-frame "VM" 0x4ac> (nil . "magenta"))
- (global ((tty) . "cyan") (nil . "white"))
- )
-
- Then, say we want to determine what the background color of the
-default face is for the window currently displaying the buffer
-`*scratch*'. We call
-
- (get-buffer-window "*scratch*")
- => #<window on "*scratch*" 0x4ad>
- (window-frame (get-buffer-window "*scratch*"))
- => #<x-frame "emacs" 0x4ac>
- (specifier-instance sp (get-buffer-window "*scratch*"))
- => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
-
- Note that we passed a window to `specifier-instance', not a buffer.
-We cannot pass a buffer because a buffer by itself does not provide
-enough information. The buffer might not be displayed anywhere at all,
-or could be displayed in many different frames on different devices.
-
- The result is arrived at like this:
-
- 1. First, we look for a specification matching the buffer displayed
- in the window, i.e. `*scratch*'. There are none, so we proceed.
-
- 2. Then, we look for a specification matching the window itself.
- Again, there are none.
-
- 3. Then, we look for a specification matching the window's frame. The
- specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
- found. We call the instantiation method for colors, passing it the
- locale we were searching over (i.e. the window, in this case) and
- the instantiator (`"puke orange"'). However, the particular device
- which this window is on (let's say it's an X connection) doesn't
- recognize the color `"puke orange"', so the specification is
- rejected.
-
- 4. So we continue looking for a specification matching the window's
- frame. We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'. Again,
- we call the instantiation method for colors. This time, the X
- server our window is on recognizes the color `moccasin', and so the
- instantiation method succeeds and returns a color instance.
-
-\1f
-File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers
-
-Creating New Specifier Objects
-==============================
-
- - Function: make-specifier type
- This function creates a new specifier.
-
- A specifier is an object that can be used to keep track of a
- property whose value can be per-buffer, per-window, per-frame, or
- per-device, and can further be restricted to a particular
- device-type or device-class. Specifiers are used, for example,
- for the various built-in properties of a face; this allows a face
- to have different values in different frames, buffers, etc. For
- more information, see `specifier-instance', `specifier-specs', and
- `add-spec-to-specifier'; or, for a detailed description of
- specifiers, including how they are instantiated over a particular
- domain (i.e. how their value in that domain is determined), see
- the chapter on specifiers in the XEmacs Lisp Reference Manual.
-
- TYPE specifies the particular type of specifier, and should be one
- of the symbols `generic', `integer', `natnum', `boolean', `color',
- `font', `image', `face-boolean', or `toolbar'.
-
- For more information on particular types of specifiers, see the
- functions `generic-specifier-p', `integer-specifier-p',
- `natnum-specifier-p', `boolean-specifier-p', `color-specifier-p',
- `font-specifier-p', `image-specifier-p',
- `face-boolean-specifier-p', and `toolbar-specifier-p'.
-
- - Function: make-specifier-and-init type spec-list &optional
- dont-canonicalize
- This function creates and initialize a new specifier.
-
- This is a front-end onto `make-specifier' that allows you to create
- a specifier and add specs to it at the same time. TYPE specifies
- the specifier type. SPEC-LIST supplies the specification(s) to be
- added to the specifier. Normally, almost any reasonable
- abbreviation of the full spec-list form is accepted, and is
- converted to the full form; however, if optional argument
- DONT-CANONICALIZE is non-`nil', this conversion is not performed,
- and the SPEC-LIST must already be in full form. See
- `canonicalize-spec-list'.
-
-\1f
-File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
-
-Functions for Checking the Validity of Specifier Components
-===========================================================
-
- - Function: valid-specifier-domain-p domain
- This function returns non-`nil' if DOMAIN is a valid specifier
- domain. A domain is used to instance a specifier (i.e. determine
- the specifier's value in that domain). Valid domains are a
- window, frame, or device. (`nil' is not valid.)
-
- - Function: valid-specifier-locale-p locale
- This function returns non-`nil' if LOCALE is a valid specifier
- locale. Valid locales are a device, a frame, a window, a buffer,
- and `global'. (`nil' is not valid.)
-
- - Function: valid-specifier-locale-type-p locale-type
- Given a specifier LOCALE-TYPE, this function returns non-nil if it
- is valid. Valid locale types are the symbols `global', `device',
- `frame', `window', and `buffer'. (Note, however, that in functions
- that accept either a locale or a locale type, `global' is
- considered an individual locale.)
-
- - Function: valid-specifier-type-p specifier-type
- Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
- valid. Valid types are `generic', `integer', `boolean', `color',
- `font', `image', `face-boolean', and `toolbar'.
-
- - Function: valid-specifier-tag-p tag
- This function returns non-`nil' if TAG is a valid specifier tag.
-
- - Function: valid-instantiator-p instantiator specifier-type
- This function returns non-`nil' if INSTANTIATOR is valid for
- SPECIFIER-TYPE.
-
- - Function: valid-inst-list-p inst-list type
- This function returns non-`nil' if INST-LIST is valid for
- specifier type TYPE.
-
- - Function: valid-spec-list-p spec-list type
- This function returns non-`nil' if SPEC-LIST is valid for
- specifier type TYPE.
-
- - Function: check-valid-instantiator instantiator specifier-type
- This function signals an error if INSTANTIATOR is invalid for
- SPECIFIER-TYPE.
-
- - Function: check-valid-inst-list inst-list type
- This function signals an error if INST-LIST is invalid for
- specifier type TYPE.
-
- - Function: check-valid-spec-list spec-list type
- This function signals an error if SPEC-LIST is invalid for
- specifier type TYPE.
-
-\1f
-File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
-
-Other Functions for Working with Specifications in a Specifier
-==============================================================
-
- - Function: copy-specifier specifier &optional dest locale tag-set
- exact-p how-to-add
- This function copies SPECIFIER to DEST, or creates a new one if
- DEST is `nil'.
-
- If DEST is `nil' or omitted, a new specifier will be created and
- the specifications copied into it. Otherwise, the specifications
- will be copied into the existing specifier in DEST.
-
- If LOCALE is `nil' or the symbol `all', all specifications will be
- copied. If LOCALE is a particular locale, the specification for
- that particular locale will be copied. If LOCALE is a locale
- type, the specifications for all locales of that type will be
- copied. LOCALE can also be a list of locales, locale types,
- and/or `all'; this is equivalent to calling `copy-specifier' for
- each of the elements of the list. See `specifier-spec-list' for
- more information about LOCALE.
-
- Only instantiators where TAG-SET (a list of zero or more tags) is
- a subset of (or possibly equal to) the instantiator's tag set are
- copied. (The default value of `nil' is a subset of all tag sets,
- so in this case no instantiators will be screened out.) If EXACT-P
- is non-`nil', however, TAG-SET must be equal to an instantiator's
- tag set for the instantiator to be copied.
-
- Optional argument HOW-TO-ADD specifies what to do with existing
- specifications in DEST. If nil, then whichever locales or locale
- types are copied will first be completely erased in DEST.
- Otherwise, it is the same as in `add-spec-to-specifier'.
-
- - Function: remove-specifier specifier &optional locale tag-set exact-p
- This function removes specification(s) for SPECIFIER.
-
- If LOCALE is a particular locale (a buffer, window, frame, device,
- or the symbol `global'), the specification for that locale will be
- removed.
-
- If instead, LOCALE is a locale type (i.e. a symbol `buffer',
- `window', `frame', or `device'), the specifications for all
- locales of that type will be removed.
-
- If LOCALE is `nil' or the symbol `all', all specifications will be
- removed.
-
- LOCALE can also be a list of locales, locale types, and/or `all';
- this is equivalent to calling `remove-specifier' for each of the
- elements in the list.
-
- Only instantiators where TAG-SET (a list of zero or more tags) is
- a subset of (or possibly equal to) the instantiator's tag set are
- removed. (The default value of `nil' is a subset of all tag sets,
- so in this case no instantiators will be screened out.) If EXACT-P
- is non-`nil', however, TAG-SET must be equal to an instantiator's
- tag set for the instantiator to be removed.
-
- - Function: map-specifier specifier func &optional locale maparg
- This function applies FUNC to the specification(s) for LOCALE in
- SPECIFIER.
-
- If LOCALE is a locale, FUNC will be called for that locale. If
- LOCALE is a locale type, FUNC will be mapped over all locales of
- that type. If LOCALE is `nil' or the symbol `all', FUNC will be
- mapped over all locales in SPECIFIER.
-
- FUNC is called with four arguments: the SPECIFIER, the locale
- being mapped over, the inst-list for that locale, and the optional
- MAPARG. If any invocation of FUNC returns non-`nil', the mapping
- will stop and the returned value becomes the value returned from
- `map-specifier'. Otherwise, `map-specifier' returns `nil'.
-
- - Function: specifier-locale-type-from-locale locale
- Given a specifier LOCALE, this function returns its type.
-
-\1f
-File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
-
-Faces and Window-System Objects
-*******************************
-
-* Menu:
-
-* Faces:: Controlling the way text looks.
-* Fonts:: Controlling the typeface of text.
-* Colors:: Controlling the color of text and pixmaps.
-
-\1f
-File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
-
-Faces
-=====
-
- A "face" is a named collection of graphical properties: font,
-foreground color, background color, background pixmap, optional
-underlining, and (on TTY devices) whether the text is to be highlighted,
-dimmed, blinking, or displayed in reverse video. Faces control the
-display of text on the screen. Every face has a name, which is a symbol
-such as `default' or `modeline'.
-
- Each built-in property of a face is controlled using a specifier,
-which allows it to have separate values in particular buffers, frames,
-windows, and devices and to further vary according to device type (X or
-TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
-for more information.
-
- The face named `default' is used for ordinary text. The face named
-`modeline' is used for displaying the modeline. The face named
-`highlight' is used for highlighted extents (*note Extents::). The
-faces named `left-margin' and `right-margin' are used for the left and
-right margin areas, respectively (*note Annotations::). The face named
-`zmacs-region' is used for the highlighted region between point and
-mark.
-
-* Menu:
-
-* Merging Faces:: How XEmacs decides which face to use
- for a character.
-* Basic Face Functions:: How to define and examine faces.
-* Face Properties:: How to access and modify a face's properties.
-* Face Convenience Functions:: Convenience functions for accessing
- particular properties of a face.
-* Other Face Display Functions:: Other functions pertaining to how a
- a face appears.
-
-\1f
-File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
-
-Merging Faces for Display
--------------------------
-
- Here are all the ways to specify which face to use for display of
-text:
-
- * With defaults. Each frame has a "default face", which is used for
- all text that doesn't somehow specify another face. The face named
- `default' applies to the text area, while the faces `left-margin'
- and `right-margin' apply to the left and right margin areas.
-
- * With text properties. A character may have a `face' property; if
- so, it's displayed with that face. (Text properties are actually
- implemented in terms of extents.) *Note Text Properties::.
-
- * With extents. An extent may have a `face' property, which applies
- to all the text covered by the extent; in addition, if the
- `highlight' property is set, the `highlight' property applies when
- the mouse moves over the extent or if the extent is explicitly
- highlighted. *Note Extents::.
-
- * With annotations. Annotations that are inserted into a buffer can
- specify their own face. (Annotations are actually implemented in
- terms of extents.) *Note Annotations::.
-
- If these various sources together specify more than one face for a
-particular character, XEmacs merges the properties of the various faces
-specified. Extents, text properties, and annotations all use the same
-underlying representation (as extents). When multiple extents cover one
-character, an extent with higher priority overrides those with lower
-priority. *Note Extents::. If no extent covers a particular character,
-the `default' face is used.
-
- If a background pixmap is specified, it determines what will be
-displayed in the background of text characters. If the background
-pixmap is actually a pixmap, with its colors specified, those colors are
-used; if it is a bitmap, the face's foreground and background colors are
-used to color it.
-
-\1f
-File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
-
-Basic Functions for Working with Faces
---------------------------------------
-
- The properties a face can specify include the font, the foreground
-color, the background color, the background pixmap, the underlining,
-the display table, and (for TTY devices) whether the text is to be
-highlighted, dimmed, blinking, or displayed in reverse video. The face
-can also leave these unspecified, causing them to assume the value of
-the corresponding property of the `default' face.
-
- Here are the basic primitives for working with faces.
-
- - Function: make-face name &optional doc-string temporary
- This function defines and returns a new face named NAME, initially
- with all properties unspecified. It does nothing if there is
- already a face named NAME. Optional argument DOC-STRING specifies
- an explanatory string used for descriptive purposes. If optional
- argument TEMPORARY is non-`nil', the face will automatically
- disappear when there are no more references to it anywhere in text
- or Lisp code (otherwise, the face will continue to exist
- indefinitely even if it is not used).
-
- - Function: face-list &optional temporary
- This function returns a list of the names of all defined faces. If
- TEMPORARY is `nil', only the permanent faces are included. If it
- is `t', only the temporary faces are included. If it is any other
- non-`nil' value both permanent and temporary are included.
-
- - Function: facep object
- This function returns whether the given object is a face.
-
- - Function: copy-face old-face new-name &optional locale how-to-add
- This function defines a new face named NEW-NAME which is a copy of
- the existing face named OLD-FACE. If there is already a face
- named NEW-NAME, then it alters the face to have the same
- properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just
- parts of the old face rather than the whole face, and are as in
- `copy-specifier' (*note Specifiers::).
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
+
+Retrieving the Specifications from a Specifier
+==============================================
+
+ - Function: specifier-spec-list specifier &optional locale tag-set
+ exact-p
+ This function returns the spec-list of specifications for
+ SPECIFIER in LOCALE.
+
+ If LOCALE is a particular locale (a window, buffer, frame, device,
+ or the symbol `global'), a spec-list consisting of the
+ specification for that locale will be returned.
+
+ If LOCALE is a locale type (i.e. a symbol `window', `buffer',
+ `frame', or `device'), a spec-list of the specifications for all
+ locales of that type will be returned.
+
+ If LOCALE is `nil' or the symbol `all', a spec-list of all
+ specifications in SPECIFIER will be returned.
+
+ LOCALE can also be a list of locales, locale types, and/or `all';
+ the result is as if `specifier-spec-list' were called on each
+ element of the list and the results concatenated together.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ returned. (The default value of` nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be returned.
+
+ - Function: specifier-specs specifier &optional locale tag-set exact-p
+ This function returns the specification(s) for SPECIFIER in LOCALE.
+
+ If LOCALE is a single locale or is a list of one element
+ containing a single locale, then a "short form" of the
+ instantiators for that locale will be returned. Otherwise, this
+ function is identical to `specifier-spec-list'.
+
+ The "short form" is designed for readability and not for ease of
+ use in Lisp programs, and is as follows:
+
+ 1. If there is only one instantiator, then an inst-pair (i.e.
+ cons of tag and instantiator) will be returned; otherwise a
+ list of inst-pairs will be returned.
+
+ 2. For each inst-pair returned, if the instantiator's tag is
+ `any', the tag will be removed and the instantiator itself
+ will be returned instead of the inst-pair.
+
+ 3. If there is only one instantiator, its value is `nil', and
+ its tag is `any', a one-element list containing `nil' will be
+ returned rather than just `nil', to distinguish this case
+ from there being no instantiators at all.
+
+
+ - Function: specifier-fallback specifier
+ This function returns the fallback value for SPECIFIER. Fallback
+ values are provided by the C code for certain built-in specifiers
+ to make sure that instancing won't fail even if all specs are
+ removed from the specifier, or to implement simple inheritance
+ behavior (e.g. this method is used to ensure that faces other than
+ `default' inherit their attributes from `default'). By design,
+ you cannot change the fallback value, and specifiers created with
+ `make-specifier' will never have a fallback (although a similar,
+ Lisp-accessible capability may be provided in the future to allow
+ for inheritance).
+
+ The fallback value will be an inst-list that is instanced like any
+ other inst-list, a specifier of the same type as SPECIFIER
+ (results in inheritance), or `nil' for no fallback.
+
+ When you instance a specifier, you can explicitly request that the
+ fallback not be consulted. (The C code does this, for example, when
+ merging faces.) See `specifier-instance'.
+
+\1f
+File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
+
+Working With Specifier Tags
+===========================
+
+ A specifier tag set is an entity that is attached to an instantiator
+and can be used to restrict the scope of that instantiator to a
+particular device class or device type and/or to mark instantiators
+added by a particular package so that they can be later removed.
+
+ A specifier tag set consists of a list of zero of more specifier
+tags, each of which is a symbol that is recognized by XEmacs as a tag.
+(The valid device types and device classes are always tags, as are any
+tags defined by `define-specifier-tag'.) It is called a "tag set" (as
+opposed to a list) because the order of the tags or the number of times
+a particular tag occurs does not matter.
+
+ Each tag has a predicate associated with it, which specifies whether
+that tag applies to a particular device. The tags which are device
+types and classes match devices of that type or class. User-defined
+tags can have any predicate, or none (meaning that all devices match).
+When attempting to instance a specifier, a particular instantiator is
+only considered if the device of the domain being instanced over matches
+all tags in the tag set attached to that instantiator.
+
+ Most of the time, a tag set is not specified, and the instantiator
+gets a null tag set, which matches all devices.
+
+ - Function: valid-specifier-tag-p tag
+ This function returns non-`nil' if TAG is a valid specifier tag.
+
+ - Function: valid-specifier-tag-set-p tag-set
+ This function returns non-`nil' if TAG-SET is a valid specifier
+ tag set.
+
+ - Function: canonicalize-tag-set tag-set
+ This function canonicalizes the given tag set. Two canonicalized
+ tag sets can be compared with `equal' to see if they represent the
+ same tag set. (Specifically, canonicalizing involves sorting by
+ symbol name and removing duplicates.)
+
+ - Function: device-matches-specifier-tag-set-p device tag-set
+ This function returns non-`nil' if DEVICE matches specifier tag
+ set TAG-SET. This means that DEVICE matches each tag in the tag
+ set.
+
+ - Function: define-specifier-tag tag &optional predicate
+ This function defines a new specifier tag. If PREDICATE is
+ specified, it should be a function of one argument (a device) that
+ specifies whether the tag matches that particular device. If
+ PREDICATE is omitted, the tag matches all devices.
+
+ You can redefine an existing user-defined specifier tag. However,
+ you cannot redefine the built-in specifier tags (the device types
+ and classes) or the symbols `nil', `t', `all', or `global'.
+
+ - Function: device-matching-specifier-tag-list &optional device
+ This function returns a list of all specifier tags matching
+ DEVICE. DEVICE defaults to the selected device if omitted.
+
+ - Function: specifier-tag-list
+ This function returns a list of all currently-defined specifier
+ tags. This includes the built-in ones (the device types and
+ classes).
+
+ - Function: specifier-tag-predicate tag
+ This function returns the predicate for the given specifier tag.
+
+\1f
+File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers
+
+Functions for Instancing a Specifier
+====================================
+
+ - Function: specifier-instance specifier &optional domain default
+ no-fallback
+ This function instantiates SPECIFIER (return its value) in DOMAIN.
+ If no instance can be generated for this domain, return DEFAULT.
+
+ DOMAIN should be a window, frame, or device. Other values that
+ are legal as a locale (e.g. a buffer) are not valid as a domain
+ because they do not provide enough information to identify a
+ particular device (see `valid-specifier-domain-p'). DOMAIN
+ defaults to the selected window if omitted.
+
+ "Instantiating" a specifier in a particular domain means
+ determining the specifier's "value" in that domain. This is
+ accomplished by searching through the specifications in the
+ specifier that correspond to all locales that can be derived from
+ the given domain, from specific to general. In most cases, the
+ domain is an Emacs window. In that case specifications are
+ searched for as follows:
+
+ 1. A specification whose locale is the window itself;
+
+ 2. A specification whose locale is the window's buffer;
+
+ 3. A specification whose locale is the window's frame;
+
+ 4. A specification whose locale is the window's frame's device;
+
+ 5. A specification whose locale is the symbol `global'.
+
+ If all of those fail, then the C-code-provided fallback value for
+ this specifier is consulted (see `specifier-fallback'). If it is
+ an inst-list, then this function attempts to instantiate that list
+ just as when a specification is located in the first five steps
+ above. If the fallback is a specifier, `specifier-instance' is
+ called recursively on this specifier and the return value used.
+ Note, however, that if the optional argument NO-FALLBACK is
+ non-`nil', the fallback value will not be consulted.
+
+ Note that there may be more than one specification matching a
+ particular locale; all such specifications are considered before
+ looking for any specifications for more general locales. Any
+ particular specification that is found may be rejected because it
+ is tagged to a particular device class (e.g. `color') or device
+ type (e.g. `x') or both and the device for the given domain does
+ not match this, or because the specification is not valid for the
+ device of the given domain (e.g. the font or color name does not
+ exist for this particular X server).
+
+ The returned value is dependent on the type of specifier. For
+ example, for a font specifier (as returned by the `face-font'
+ function), the returned value will be a font-instance object. For
+ images, the returned value will be a string, pixmap, or subwindow.
+
+ - Function: specifier-instance-from-inst-list specifier domain
+ inst-list &optional default
+ This function attempts to convert a particular inst-list into an
+ instance. This attempts to instantiate INST-LIST in the given
+ DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
+ If the instantiation fails, DEFAULT is returned. In most
+ circumstances, you should not use this function; use
+ `specifier-instance' instead.
+
+\1f
+File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
+
+Example of Specifier Usage
+==========================
+
+ Now let us present an example to clarify the theoretical discussions
+we have been through. In this example, we will use the general
+specifier functions for clarity. Keep in mind that many types of
+specifiers, and some other types of objects that are associated with
+specifiers (e.g. faces), provide convenience functions making it easier
+to work with objects of that type.
+
+ Let us consider the background color of the default face. A
+specifier is used to specify how that color will appear in different
+domains. First, let's retrieve the specifier:
+
+ (setq sp (face-property 'default 'background))
+ => #<color-specifier 0x3da>
+
+ (specifier-specs sp)
+ => ((#<buffer "device.c"> (nil . "forest green"))
+ (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
+ (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
+ (nil . "moccasin"))
+ (#<x-frame "VM" 0x4ac> (nil . "magenta"))
+ (global ((tty) . "cyan") (nil . "white"))
+ )
+
+ Then, say we want to determine what the background color of the
+default face is for the window currently displaying the buffer
+`*scratch*'. We call
+
+ (get-buffer-window "*scratch*")
+ => #<window on "*scratch*" 0x4ad>
+ (window-frame (get-buffer-window "*scratch*"))
+ => #<x-frame "emacs" 0x4ac>
+ (specifier-instance sp (get-buffer-window "*scratch*"))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
+
+ Note that we passed a window to `specifier-instance', not a buffer.
+We cannot pass a buffer because a buffer by itself does not provide
+enough information. The buffer might not be displayed anywhere at all,
+or could be displayed in many different frames on different devices.
+
+ The result is arrived at like this:
+
+ 1. First, we look for a specification matching the buffer displayed
+ in the window, i.e. `*scratch*'. There are none, so we proceed.
+
+ 2. Then, we look for a specification matching the window itself.
+ Again, there are none.
+
+ 3. Then, we look for a specification matching the window's frame. The
+ specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
+ found. We call the instantiation method for colors, passing it the
+ locale we were searching over (i.e. the window, in this case) and
+ the instantiator (`"puke orange"'). However, the particular device
+ which this window is on (let's say it's an X connection) doesn't
+ recognize the color `"puke orange"', so the specification is
+ rejected.
+
+ 4. So we continue looking for a specification matching the window's
+ frame. We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'. Again,
+ we call the instantiation method for colors. This time, the X
+ server our window is on recognizes the color `moccasin', and so the
+ instantiation method succeeds and returns a color instance.
+
+\1f
+File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers
+
+Creating New Specifier Objects
+==============================
+
+ - Function: make-specifier type
+ This function creates a new specifier.
+
+ A specifier is an object that can be used to keep track of a
+ property whose value can be per-buffer, per-window, per-frame, or
+ per-device, and can further be restricted to a particular
+ device-type or device-class. Specifiers are used, for example,
+ for the various built-in properties of a face; this allows a face
+ to have different values in different frames, buffers, etc. For
+ more information, see `specifier-instance', `specifier-specs', and
+ `add-spec-to-specifier'; or, for a detailed description of
+ specifiers, including how they are instantiated over a particular
+ domain (i.e. how their value in that domain is determined), see
+ the chapter on specifiers in the XEmacs Lisp Reference Manual.
+
+ TYPE specifies the particular type of specifier, and should be one
+ of the symbols `generic', `integer', `natnum', `boolean', `color',
+ `font', `image', `face-boolean', or `toolbar'.
+
+ For more information on particular types of specifiers, see the
+ functions `generic-specifier-p', `integer-specifier-p',
+ `natnum-specifier-p', `boolean-specifier-p', `color-specifier-p',
+ `font-specifier-p', `image-specifier-p',
+ `face-boolean-specifier-p', and `toolbar-specifier-p'.
+
+ - Function: make-specifier-and-init type spec-list &optional
+ dont-canonicalize
+ This function creates and initialize a new specifier.
+
+ This is a front-end onto `make-specifier' that allows you to create
+ a specifier and add specs to it at the same time. TYPE specifies
+ the specifier type. SPEC-LIST supplies the specification(s) to be
+ added to the specifier. Normally, almost any reasonable
+ abbreviation of the full spec-list form is accepted, and is
+ converted to the full form; however, if optional argument
+ DONT-CANONICALIZE is non-`nil', this conversion is not performed,
+ and the SPEC-LIST must already be in full form. See
+ `canonicalize-spec-list'.
+
+\1f
+File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
+
+Functions for Checking the Validity of Specifier Components
+===========================================================
+
+ - Function: valid-specifier-domain-p domain
+ This function returns non-`nil' if DOMAIN is a valid specifier
+ domain. A domain is used to instance a specifier (i.e. determine
+ the specifier's value in that domain). Valid domains are a
+ window, frame, or device. (`nil' is not valid.)
+
+ - Function: valid-specifier-locale-p locale
+ This function returns non-`nil' if LOCALE is a valid specifier
+ locale. Valid locales are a device, a frame, a window, a buffer,
+ and `global'. (`nil' is not valid.)
+
+ - Function: valid-specifier-locale-type-p locale-type
+ Given a specifier LOCALE-TYPE, this function returns non-nil if it
+ is valid. Valid locale types are the symbols `global', `device',
+ `frame', `window', and `buffer'. (Note, however, that in functions
+ that accept either a locale or a locale type, `global' is
+ considered an individual locale.)
+
+ - Function: valid-specifier-type-p specifier-type
+ Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
+ valid. Valid types are `generic', `integer', `boolean', `color',
+ `font', `image', `face-boolean', and `toolbar'.
+
+ - Function: valid-specifier-tag-p tag
+ This function returns non-`nil' if TAG is a valid specifier tag.
+
+ - Function: valid-instantiator-p instantiator specifier-type
+ This function returns non-`nil' if INSTANTIATOR is valid for
+ SPECIFIER-TYPE.
+
+ - Function: valid-inst-list-p inst-list type
+ This function returns non-`nil' if INST-LIST is valid for
+ specifier type TYPE.
+
+ - Function: valid-spec-list-p spec-list type
+ This function returns non-`nil' if SPEC-LIST is valid for
+ specifier type TYPE.
+
+ - Function: check-valid-instantiator instantiator specifier-type
+ This function signals an error if INSTANTIATOR is invalid for
+ SPECIFIER-TYPE.
+
+ - Function: check-valid-inst-list inst-list type
+ This function signals an error if INST-LIST is invalid for
+ specifier type TYPE.
+
+ - Function: check-valid-spec-list spec-list type
+ This function signals an error if SPEC-LIST is invalid for
+ specifier type TYPE.
+
+\1f
+File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
+
+Other Functions for Working with Specifications in a Specifier
+==============================================================
+
+ - Function: copy-specifier specifier &optional dest locale tag-set
+ exact-p how-to-add
+ This function copies SPECIFIER to DEST, or creates a new one if
+ DEST is `nil'.
+
+ If DEST is `nil' or omitted, a new specifier will be created and
+ the specifications copied into it. Otherwise, the specifications
+ will be copied into the existing specifier in DEST.
+
+ If LOCALE is `nil' or the symbol `all', all specifications will be
+ copied. If LOCALE is a particular locale, the specification for
+ that particular locale will be copied. If LOCALE is a locale
+ type, the specifications for all locales of that type will be
+ copied. LOCALE can also be a list of locales, locale types,
+ and/or `all'; this is equivalent to calling `copy-specifier' for
+ each of the elements of the list. See `specifier-spec-list' for
+ more information about LOCALE.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ copied. (The default value of `nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be copied.
+
+ Optional argument HOW-TO-ADD specifies what to do with existing
+ specifications in DEST. If nil, then whichever locales or locale
+ types are copied will first be completely erased in DEST.
+ Otherwise, it is the same as in `add-spec-to-specifier'.
+
+ - Function: remove-specifier specifier &optional locale tag-set exact-p
+ This function removes specification(s) for SPECIFIER.
+
+ If LOCALE is a particular locale (a buffer, window, frame, device,
+ or the symbol `global'), the specification for that locale will be
+ removed.
+
+ If instead, LOCALE is a locale type (i.e. a symbol `buffer',
+ `window', `frame', or `device'), the specifications for all
+ locales of that type will be removed.
+
+ If LOCALE is `nil' or the symbol `all', all specifications will be
+ removed.
+
+ LOCALE can also be a list of locales, locale types, and/or `all';
+ this is equivalent to calling `remove-specifier' for each of the
+ elements in the list.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ removed. (The default value of `nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be removed.
+
+ - Function: map-specifier specifier func &optional locale maparg
+ This function applies FUNC to the specification(s) for LOCALE in
+ SPECIFIER.
+
+ If LOCALE is a locale, FUNC will be called for that locale. If
+ LOCALE is a locale type, FUNC will be mapped over all locales of
+ that type. If LOCALE is `nil' or the symbol `all', FUNC will be
+ mapped over all locales in SPECIFIER.
+
+ FUNC is called with four arguments: the SPECIFIER, the locale
+ being mapped over, the inst-list for that locale, and the optional
+ MAPARG. If any invocation of FUNC returns non-`nil', the mapping
+ will stop and the returned value becomes the value returned from
+ `map-specifier'. Otherwise, `map-specifier' returns `nil'.
+
+ - Function: specifier-locale-type-from-locale locale
+ Given a specifier LOCALE, this function returns its type.
+
+\1f
+File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
+
+Faces and Window-System Objects
+*******************************
+
+* Menu:
+
+* Faces:: Controlling the way text looks.
+* Fonts:: Controlling the typeface of text.
+* Colors:: Controlling the color of text and pixmaps.
+
+\1f
+File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
+
+Faces
+=====
+
+ A "face" is a named collection of graphical properties: font,
+foreground color, background color, background pixmap, optional
+underlining, and (on TTY devices) whether the text is to be highlighted,
+dimmed, blinking, or displayed in reverse video. Faces control the
+display of text on the screen. Every face has a name, which is a symbol
+such as `default' or `modeline'.
+
+ Each built-in property of a face is controlled using a specifier,
+which allows it to have separate values in particular buffers, frames,
+windows, and devices and to further vary according to device type (X or
+TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
+for more information.
+
+ The face named `default' is used for ordinary text. The face named
+`modeline' is used for displaying the modeline. The face named
+`highlight' is used for highlighted extents (*note Extents::). The
+faces named `left-margin' and `right-margin' are used for the left and
+right margin areas, respectively (*note Annotations::). The face named
+`zmacs-region' is used for the highlighted region between point and
+mark.
+
+* Menu:
+
+* Merging Faces:: How XEmacs decides which face to use
+ for a character.
+* Basic Face Functions:: How to define and examine faces.
+* Face Properties:: How to access and modify a face's properties.
+* Face Convenience Functions:: Convenience functions for accessing
+ particular properties of a face.
+* Other Face Display Functions:: Other functions pertaining to how a
+ a face appears.
+
+\1f
+File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
+
+Merging Faces for Display
+-------------------------
+
+ Here are all the ways to specify which face to use for display of
+text:
+
+ * With defaults. Each frame has a "default face", which is used for
+ all text that doesn't somehow specify another face. The face named
+ `default' applies to the text area, while the faces `left-margin'
+ and `right-margin' apply to the left and right margin areas.
+
+ * With text properties. A character may have a `face' property; if
+ so, it's displayed with that face. (Text properties are actually
+ implemented in terms of extents.) *Note Text Properties::.
+
+ * With extents. An extent may have a `face' property, which applies
+ to all the text covered by the extent; in addition, if the
+ `highlight' property is set, the `highlight' property applies when
+ the mouse moves over the extent or if the extent is explicitly
+ highlighted. *Note Extents::.
+
+ * With annotations. Annotations that are inserted into a buffer can
+ specify their own face. (Annotations are actually implemented in
+ terms of extents.) *Note Annotations::.
+
+ If these various sources together specify more than one face for a
+particular character, XEmacs merges the properties of the various faces
+specified. Extents, text properties, and annotations all use the same
+underlying representation (as extents). When multiple extents cover one
+character, an extent with higher priority overrides those with lower
+priority. *Note Extents::. If no extent covers a particular character,
+the `default' face is used.
+
+ If a background pixmap is specified, it determines what will be
+displayed in the background of text characters. If the background
+pixmap is actually a pixmap, with its colors specified, those colors are
+used; if it is a bitmap, the face's foreground and background colors are
+used to color it.
+
+\1f
+File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
+
+Basic Functions for Working with Faces
+--------------------------------------
+
+ The properties a face can specify include the font, the foreground
+color, the background color, the background pixmap, the underlining,
+the display table, and (for TTY devices) whether the text is to be
+highlighted, dimmed, blinking, or displayed in reverse video. The face
+can also leave these unspecified, causing them to assume the value of
+the corresponding property of the `default' face.
+
+ Here are the basic primitives for working with faces.
+
+ - Function: make-face name &optional doc-string temporary
+ This function defines and returns a new face named NAME, initially
+ with all properties unspecified. It does nothing if there is
+ already a face named NAME. Optional argument DOC-STRING specifies
+ an explanatory string used for descriptive purposes. If optional
+ argument TEMPORARY is non-`nil', the face will automatically
+ disappear when there are no more references to it anywhere in text
+ or Lisp code (otherwise, the face will continue to exist
+ indefinitely even if it is not used).
+
+ - Function: face-list &optional temporary
+ This function returns a list of the names of all defined faces. If
+ TEMPORARY is `nil', only the permanent faces are included. If it
+ is `t', only the temporary faces are included. If it is any other
+ non-`nil' value both permanent and temporary are included.
+
+ - Function: facep object
+ This function returns whether the given object is a face.
+
+ - Function: copy-face old-face new-name &optional locale how-to-add
+ This function defines a new face named NEW-NAME which is a copy of
+ the existing face named OLD-FACE. If there is already a face
+ named NEW-NAME, then it alters the face to have the same
+ properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just
+ parts of the old face rather than the whole face, and are as in
+ `copy-specifier' (*note Specifiers::).
+
+\1f
File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
Face Properties
- Function: color-specifier-p object
This function returns non-`nil' if OBJECT is a color specifier.
-\1f
-File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
-
-Color Instances
----------------
-
- A "color-instance object" is an object describing the way a color
-specifier is instanced in a particular domain. Functions such as
-`face-background-instance' return a color-instance object. For example,
-
- (face-background-instance 'default (next-window))
- => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
-
- The color-instance object returned describes the way the background
-color of the `default' face is displayed in the next window after the
-selected one.
-
- - Function: color-instance-p object
- This function returns non-`nil' if OBJECT is a color-instance.
-
-\1f
-File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
-
-Color Instance Properties
--------------------------
-
- - Function: color-instance-name color-instance
- This function returns the name used to allocate COLOR-INSTANCE.
-
- - Function: color-instance-rgb-components color-instance
- This function returns a three element list containing the red,
- green, and blue color components of COLOR-INSTANCE.
-
- (color-instance-rgb-components
- (face-background-instance 'default (next-window)))
- => (65535 58596 46517)
-
-\1f
-File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
-
-Color Convenience Functions
----------------------------
-
- - Function: color-name color &optional domain
- This function returns the name of the COLOR in the specified
- DOMAIN, if any. COLOR should be a color specifier object and
- DOMAIN is normally a window and defaults to the selected window if
- omitted. This is equivalent to using `specifier-instance' and
- applying `color-instance-name' to the result.
-
- - Function: color-rgb-components color &optional domain
- This function returns the RGB components of the COLOR in the
- specified DOMAIN, if any. COLOR should be a color specifier
- object and DOMAIN is normally a window and defaults to the
- selected window if omitted. This is equivalent to using
- `specifier-instance' and applying `color-instance-rgb-components'
- to the result.
-
- (color-rgb-components (face-background 'default (next-window)))
- => (65535 58596 46517)
-
-\1f
-File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
-
-Glyphs
-******
-
- A "glyph" is an object that is used for pixmaps and images of all
-sorts, as well as for things that "act" like pixmaps, such as
-non-textual strings ("annotations") displayed in a buffer or in the
-margins. It is used in begin-glyphs and end-glyphs attached to extents,
-marginal and textual annotations, overlay arrows (`overlay-arrow-*'
-variables), toolbar buttons, mouse pointers, frame icons, truncation and
-continuation markers, and the like. (Basically, any place there is an
-image or something that acts like an image, there will be a glyph object
-representing it.)
-
- The actual image that is displayed (as opposed to its position or
-clipping) is defined by an "image specifier" object contained within
-the glyph. The separation between an image specifier object and a
-glyph object is made because the glyph includes other properties than
-just the actual image: e.g. the face it is displayed in (for text
-images), the alignment of the image (when it is in a buffer), etc.
-
- - Function: glyphp object
- This function returns `t' if OBJECT is a glyph.
-
-* Menu:
-
-* Glyph Functions:: Functions for working with glyphs.
-* Images:: Graphical images displayed in a frame.
-* Glyph Types:: Each glyph has a particular type.
-* Mouse Pointer:: Controlling the mouse pointer.
-* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
-* Subwindows:: Inserting an externally-controlled subwindow
- into a buffer.
-
-\1f
-File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
-
-Glyph Functions
-===============
-
-* Menu:
-
-* Creating Glyphs:: Creating new glyphs.
-* Glyph Properties:: Accessing and modifying a glyph's properties.
-* Glyph Convenience Functions::
- Convenience functions for accessing particular
- properties of a glyph.
-* Glyph Dimensions:: Determining the height, width, etc. of a glyph.
-
-\1f
-File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
-
-Creating Glyphs
----------------
-
- - Function: make-glyph &optional spec-list type
- This function creates a new glyph object of type TYPE.
-
- SPEC-LIST is used to initialize the glyph's image. It is
- typically an image instantiator (a string or a vector; *Note Image
- Specifiers::), but can also be a list of such instantiators (each
- one in turn is tried until an image is successfully produced), a
- cons of a locale (frame, buffer, etc.) and an instantiator, a list
- of such conses, or any other form accepted by
- `canonicalize-spec-list'. *Note Specifiers::, for more
- information about specifiers.
-
- TYPE specifies the type of the glyph, which specifies in which
- contexts the glyph can be used, and controls the allowable image
- types into which the glyph's image can be instantiated. TYPE
- should be one of `buffer' (used for glyphs in an extent, the
- modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
- for the mouse-pointer), or `icon' (used for a frame's icon), and
- defaults to `buffer'. *Note Glyph Types::.
-
- - Function: make-glyph-internal &optional type
- This function creates a new, uninitialized glyph of type TYPE.
-
- - Function: make-pointer-glyph &optional spec-list
- This function is equivalent to calling `make-glyph' with a TYPE of
- `pointer'.
-
- - Function: make-icon-glyph &optional spec-list
- This function is equivalent to calling `make-glyph' with a TYPE of
- `icon'.
-
-\1f
-File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
-
-Glyph Properties
-----------------
-
- Each glyph has a list of properties, which control all of the
-aspects of the glyph's appearance. The following symbols have
-predefined meanings:
-
-`image'
- The image used to display the glyph.
-
-`baseline'
- Percent above baseline that glyph is to be displayed. Only for
- glyphs displayed inside of a buffer.
-
-`contrib-p'
- Whether the glyph contributes to the height of the line it's on.
- Only for glyphs displayed inside of a buffer.
-
-`face'
- Face of this glyph (_not_ a specifier).
-
- - Function: set-glyph-property glyph property value &optional locale
- tag-set how-to-add
- This function changes a property of a GLYPH.
-
- For built-in properties, the actual value of the property is a
- specifier and you cannot change this; but you can change the
- specifications within the specifier, and that is what this
- function will do. For user-defined properties, you can use this
- function to either change the actual value of the property or, if
- this value is a specifier, change the specifications within it.
-
- If PROPERTY is a built-in property, the specifications to be added
- to this property can be supplied in many different ways:
-
- * If VALUE is a simple instantiator (e.g. a string naming a
- pixmap filename) or a list of instantiators, then the
- instantiator(s) will be added as a specification of the
- property for the given LOCALE (which defaults to `global' if
- omitted).
-
- * If VALUE is a list of specifications (each of which is a cons
- of a locale and a list of instantiators), then LOCALE must be
- `nil' (it does not make sense to explicitly specify a locale
- in this case), and specifications will be added as given.
-
- * If VALUE is a specifier (as would be returned by
- `glyph-property' if no LOCALE argument is given), then some
- or all of the specifications in the specifier will be added
- to the property. In this case, the function is really
- equivalent to `copy-specifier' and LOCALE has the same
- semantics (if it is a particular locale, the specification
- for the locale will be copied; if a locale type,
- specifications for all locales of that type will be copied;
- if `nil' or `all', then all specifications will be copied).
-
- HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
- `append', `remove-tag-set-prepend', `remove-tag-set-append',
- `remove-locale', `remove-locale-type', or `remove-all'. See
- `copy-specifier' and `add-spec-to-specifier' for a description of
- what each of these means. Most of the time, you do not need to
- worry about this argument; the default behavior usually is fine.
-
- In general, it is OK to pass an instance object (e.g. as returned
- by `glyph-property-instance') as an instantiator in place of an
- actual instantiator. In such a case, the instantiator used to
- create that instance object will be used (for example, if you set
- a font-instance object as the value of the `font' property, then
- the font name used to create that object will be used instead).
- If some cases, however, doing this conversion does not make sense,
- and this will be noted in the documentation for particular types
- of instance objects.
-
- If PROPERTY is not a built-in property, then this function will
- simply set its value if LOCALE is `nil'. However, if LOCALE is
- given, then this function will attempt to add VALUE as the
- instantiator for the given LOCALE, using `add-spec-to-specifier'.
- If the value of the property is not a specifier, it will
- automatically be converted into a `generic' specifier.
-
- - Function: glyph-property glyph property &optional locale
- This function returns GLYPH's value of the given PROPERTY.
-
- If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
- be returned. For built-in properties, this will be a specifier
- object of a type appropriate to the property (e.g. a font or color
- specifier). For other properties, this could be anything.
-
- If LOCALE is supplied, then instead of returning the actual value,
- the specification(s) for the given locale or locale type will be
- returned. This will only work if the actual value of PROPERTY is
- a specifier (this will always be the case for built-in properties,
- but may or may not apply to user-defined properties). If the
- actual value of PROPERTY is not a specifier, this value will
- simply be returned regardless of LOCALE.
-
- The return value will be a list of instantiators (e.g. vectors
- specifying pixmap data), or a list of specifications, each of
- which is a cons of a locale and a list of instantiators.
- Specifically, if LOCALE is a particular locale (a buffer, window,
- frame, device, or `global'), a list of instantiators for that
- locale will be returned. Otherwise, if LOCALE is a locale type
- (one of the symbols `buffer', `window', `frame', or `device'), the
- specifications for all locales of that type will be returned.
- Finally, if LOCALE is `all', the specifications for all locales of
- all types will be returned.
-
- The specifications in a specifier determine what the value of
- PROPERTY will be in a particular "domain" or set of circumstances,
- which is typically a particular Emacs window along with the buffer
- it contains and the frame and device it lies within. The value is
- derived from the instantiator associated with the most specific
- locale (in the order buffer, window, frame, device, and `global')
- that matches the domain in question. In other words, given a
- domain (i.e. an Emacs window, usually), the specifier for PROPERTY
- will first be searched for a specification whose locale is the
- buffer contained within that window; then for a specification
- whose locale is the window itself; then for a specification whose
- locale is the frame that the window is contained within; etc. The
- first instantiator that is valid for the domain (usually this
- means that the instantiator is recognized by the device [i.e. the
- X server or TTY device] that the domain is on). The function
- `glyph-property-instance' actually does all this, and is used to
- determine how to display the glyph.
-
- - Function: glyph-property-instance glyph property &optional domain
- default no-fallback
- This function returns the instance of GLYPH's PROPERTY in the
- specified DOMAIN.
-
- Under most circumstances, DOMAIN will be a particular window, and
- the returned instance describes how the specified property
- actually is displayed for that window and the particular buffer in
- it. Note that this may not be the same as how the property
- appears when the buffer is displayed in a different window or
- frame, or how the property appears in the same window if you
- switch to another buffer in that window; and in those cases, the
- returned instance would be different.
-
- The returned instance is an image-instance object, and you can
- query it using the appropriate image instance functions. For
- example, you could use `image-instance-depth' to find out the
- depth (number of color planes) of a pixmap displayed in a
- particular window. The results might be different from the
- results you would get for another window (perhaps the user
- specified a different image for the frame that window is on; or
- perhaps the same image was specified but the window is on a
- different X server, and that X server has different color
- capabilities from this one).
-
- DOMAIN defaults to the selected window if omitted.
-
- DOMAIN can be a frame or device, instead of a window. The value
- returned for such a domain is used in special circumstances when a
- more specific domain does not apply; for example, a frame value
- might be used for coloring a toolbar, which is conceptually
- attached to a frame rather than a particular window. The value is
- also useful in determining what the value would be for a
- particular window within the frame or device, if it is not
- overridden by a more specific specification.
-
- If PROPERTY does not name a built-in property, its value will
- simply be returned unless it is a specifier object, in which case
- it will be instanced using `specifier-instance'.
-
- Optional arguments DEFAULT and NO-FALLBACK are the same as in
- `specifier-instance'. *Note Specifiers::.
-
- - Function: remove-glyph-property glyph property &optional locale
- tag-set exact-p
- This function removes a property from a glyph. For built-in
- properties, this is analogous to `remove-specifier'. *Note
- remove-specifier-p: Specifiers, for the meaning of the LOCALE,
- TAG-SET, and EXACT-P arguments.
-
-\1f
-File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
-
-Glyph Convenience Functions
----------------------------
-
- The following functions are provided for working with specific
-properties of a glyph. Note that these are exactly like calling the
-general functions described above and passing in the appropriate value
-for PROPERTY.
-
- Remember that if you want to determine the "value" of a specific
-glyph property, you probably want to use the `*-instance' functions.
-For example, to determine whether a glyph contributes to its line
-height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
-latter will return a boolean specifier or a list of specifications, and
-you probably aren't concerned with these.)
-
- - Function: glyph-image glyph &optional locale
- This function is equivalent to calling `glyph-property' with a
- property of `image'. The return value will be an image specifier
- if LOCALE is `nil' or omitted; otherwise, it will be a
- specification or list of specifications.
-
- - Function: set-glyph-image glyph spec &optional locale tag-set
- how-to-add
- This function is equivalent to calling `set-glyph-property' with a
- property of `image'.
-
- - Function: glyph-image-instance glyph &optional domain default
- no-fallback
- This function returns the instance of GLYPH's image in the given
- DOMAIN, and is equivalent to calling `glyph-property-instance'
- with a property of `image'. The return value will be an image
- instance.
-
- Normally DOMAIN will be a window or `nil' (meaning the selected
- window), and an instance object describing how the image appears
- in that particular window and buffer will be returned.
-
- - Function: glyph-contrib-p glyph &optional locale
- This function is equivalent to calling `glyph-property' with a
- property of `contrib-p'. The return value will be a boolean
- specifier if LOCALE is `nil' or omitted; otherwise, it will be a
- specification or list of specifications.
-
- - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
- how-to-add
- This function is equivalent to calling `set-glyph-property' with a
- property of `contrib-p'.
-
- - Function: glyph-contrib-p-instance glyph &optional domain default
- no-fallback
- This function returns whether the glyph contributes to its line
- height in the given DOMAIN, and is equivalent to calling
- `glyph-property-instance' with a property of `contrib-p'. The
- return value will be either `nil' or `t'. (Normally DOMAIN will be
- a window or `nil', meaning the selected window.)
-
- - Function: glyph-baseline glyph &optional locale
- This function is equivalent to calling `glyph-property' with a
- property of `baseline'. The return value will be a specifier if
- LOCALE is `nil' or omitted; otherwise, it will be a specification
- or list of specifications.
-
- - Function: set-glyph-baseline glyph spec &optional locale tag-set
- how-to-add
- This function is equivalent to calling `set-glyph-property' with a
- property of `baseline'.
-
- - Function: glyph-baseline-instance glyph &optional domain default
- no-fallback
- This function returns the instance of GLYPH's baseline value in
- the given DOMAIN, and is equivalent to calling
- `glyph-property-instance' with a property of `baseline'. The
- return value will be an integer or `nil'.
-
- Normally DOMAIN will be a window or `nil' (meaning the selected
- window), and an instance object describing the baseline value
- appears in that particular window and buffer will be returned.
-
- - Function: glyph-face glyph
- This function returns the face of GLYPH. (Remember, this is not a
- specifier, but a simple property.)
-
- - Function: set-glyph-face glyph face
- This function changes the face of GLYPH to FACE.
-
-\1f
-File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
-
-Glyph Dimensions
-----------------
-
- - Function: glyph-width glyph &optional window
- This function returns the width of GLYPH on WINDOW. This may not
- be exact as it does not take into account all of the context that
- redisplay will.
-
- - Function: glyph-ascent glyph &optional window
- This function returns the ascent value of GLYPH on WINDOW. This
- may not be exact as it does not take into account all of the
- context that redisplay will.
-
- - Function: glyph-descent glyph &optional window
- This function returns the descent value of GLYPH on WINDOW. This
- may not be exact as it does not take into account all of the
- context that redisplay will.
-
- - Function: glyph-height glyph &optional window
- This function returns the height of GLYPH on WINDOW. (This is
- equivalent to the sum of the ascent and descent values.) This may
- not be exact as it does not take into account all of the context
- that redisplay will.
-
-\1f
-File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
-
-Images
-======
-
-* Menu:
-
-* Image Specifiers:: Specifying how an image will appear.
-* Image Instantiator Conversion::
- Conversion is applied to image instantiators
- at the time they are added to an
- image specifier or at the time they
- are passed to `make-image-instance'.
-* Image Instances:: What an image specifier gets instanced as.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
+
+Color Instances
+---------------
+
+ A "color-instance object" is an object describing the way a color
+specifier is instanced in a particular domain. Functions such as
+`face-background-instance' return a color-instance object. For example,
+
+ (face-background-instance 'default (next-window))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
+
+ The color-instance object returned describes the way the background
+color of the `default' face is displayed in the next window after the
+selected one.
+
+ - Function: color-instance-p object
+ This function returns non-`nil' if OBJECT is a color-instance.
+
+\1f
+File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
+
+Color Instance Properties
+-------------------------
+
+ - Function: color-instance-name color-instance
+ This function returns the name used to allocate COLOR-INSTANCE.
+
+ - Function: color-instance-rgb-components color-instance
+ This function returns a three element list containing the red,
+ green, and blue color components of COLOR-INSTANCE.
+
+ (color-instance-rgb-components
+ (face-background-instance 'default (next-window)))
+ => (65535 58596 46517)
+
+\1f
+File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
+
+Color Convenience Functions
+---------------------------
+
+ - Function: color-name color &optional domain
+ This function returns the name of the COLOR in the specified
+ DOMAIN, if any. COLOR should be a color specifier object and
+ DOMAIN is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `color-instance-name' to the result.
+
+ - Function: color-rgb-components color &optional domain
+ This function returns the RGB components of the COLOR in the
+ specified DOMAIN, if any. COLOR should be a color specifier
+ object and DOMAIN is normally a window and defaults to the
+ selected window if omitted. This is equivalent to using
+ `specifier-instance' and applying `color-instance-rgb-components'
+ to the result.
+
+ (color-rgb-components (face-background 'default (next-window)))
+ => (65535 58596 46517)
+
+\1f
+File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
+
+Glyphs
+******
+
+ A "glyph" is an object that is used for pixmaps and images of all
+sorts, as well as for things that "act" like pixmaps, such as
+non-textual strings ("annotations") displayed in a buffer or in the
+margins. It is used in begin-glyphs and end-glyphs attached to extents,
+marginal and textual annotations, overlay arrows (`overlay-arrow-*'
+variables), toolbar buttons, mouse pointers, frame icons, truncation and
+continuation markers, and the like. (Basically, any place there is an
+image or something that acts like an image, there will be a glyph object
+representing it.)
+
+ The actual image that is displayed (as opposed to its position or
+clipping) is defined by an "image specifier" object contained within
+the glyph. The separation between an image specifier object and a
+glyph object is made because the glyph includes other properties than
+just the actual image: e.g. the face it is displayed in (for text
+images), the alignment of the image (when it is in a buffer), etc.
+
+ - Function: glyphp object
+ This function returns `t' if OBJECT is a glyph.
+
+* Menu:
+
+* Glyph Functions:: Functions for working with glyphs.
+* Images:: Graphical images displayed in a frame.
+* Glyph Types:: Each glyph has a particular type.
+* Mouse Pointer:: Controlling the mouse pointer.
+* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
+* Subwindows:: Inserting an externally-controlled subwindow
+ into a buffer.
+
+\1f
+File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
+
+Glyph Functions
+===============
+
+* Menu:
+
+* Creating Glyphs:: Creating new glyphs.
+* Glyph Properties:: Accessing and modifying a glyph's properties.
+* Glyph Convenience Functions::
+ Convenience functions for accessing particular
+ properties of a glyph.
+* Glyph Dimensions:: Determining the height, width, etc. of a glyph.
+
+\1f
+File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
+
+Creating Glyphs
+---------------
+
+ - Function: make-glyph &optional spec-list type
+ This function creates a new glyph object of type TYPE.
+
+ SPEC-LIST is used to initialize the glyph's image. It is
+ typically an image instantiator (a string or a vector; *Note Image
+ Specifiers::), but can also be a list of such instantiators (each
+ one in turn is tried until an image is successfully produced), a
+ cons of a locale (frame, buffer, etc.) and an instantiator, a list
+ of such conses, or any other form accepted by
+ `canonicalize-spec-list'. *Note Specifiers::, for more
+ information about specifiers.
+
+ TYPE specifies the type of the glyph, which specifies in which
+ contexts the glyph can be used, and controls the allowable image
+ types into which the glyph's image can be instantiated. TYPE
+ should be one of `buffer' (used for glyphs in an extent, the
+ modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
+ for the mouse-pointer), or `icon' (used for a frame's icon), and
+ defaults to `buffer'. *Note Glyph Types::.
+
+ - Function: make-glyph-internal &optional type
+ This function creates a new, uninitialized glyph of type TYPE.
+
+ - Function: make-pointer-glyph &optional spec-list
+ This function is equivalent to calling `make-glyph' with a TYPE of
+ `pointer'.
+
+ - Function: make-icon-glyph &optional spec-list
+ This function is equivalent to calling `make-glyph' with a TYPE of
+ `icon'.
+
+\1f
+File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
+
+Glyph Properties
+----------------
+
+ Each glyph has a list of properties, which control all of the
+aspects of the glyph's appearance. The following symbols have
+predefined meanings:
+
+`image'
+ The image used to display the glyph.
+
+`baseline'
+ Percent above baseline that glyph is to be displayed. Only for
+ glyphs displayed inside of a buffer.
+
+`contrib-p'
+ Whether the glyph contributes to the height of the line it's on.
+ Only for glyphs displayed inside of a buffer.
+
+`face'
+ Face of this glyph (_not_ a specifier).
+
+ - Function: set-glyph-property glyph property value &optional locale
+ tag-set how-to-add
+ This function changes a property of a GLYPH.
+
+ For built-in properties, the actual value of the property is a
+ specifier and you cannot change this; but you can change the
+ specifications within the specifier, and that is what this
+ function will do. For user-defined properties, you can use this
+ function to either change the actual value of the property or, if
+ this value is a specifier, change the specifications within it.
+
+ If PROPERTY is a built-in property, the specifications to be added
+ to this property can be supplied in many different ways:
+
+ * If VALUE is a simple instantiator (e.g. a string naming a
+ pixmap filename) or a list of instantiators, then the
+ instantiator(s) will be added as a specification of the
+ property for the given LOCALE (which defaults to `global' if
+ omitted).
+
+ * If VALUE is a list of specifications (each of which is a cons
+ of a locale and a list of instantiators), then LOCALE must be
+ `nil' (it does not make sense to explicitly specify a locale
+ in this case), and specifications will be added as given.
+
+ * If VALUE is a specifier (as would be returned by
+ `glyph-property' if no LOCALE argument is given), then some
+ or all of the specifications in the specifier will be added
+ to the property. In this case, the function is really
+ equivalent to `copy-specifier' and LOCALE has the same
+ semantics (if it is a particular locale, the specification
+ for the locale will be copied; if a locale type,
+ specifications for all locales of that type will be copied;
+ if `nil' or `all', then all specifications will be copied).
+
+ HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
+ `append', `remove-tag-set-prepend', `remove-tag-set-append',
+ `remove-locale', `remove-locale-type', or `remove-all'. See
+ `copy-specifier' and `add-spec-to-specifier' for a description of
+ what each of these means. Most of the time, you do not need to
+ worry about this argument; the default behavior usually is fine.
+
+ In general, it is OK to pass an instance object (e.g. as returned
+ by `glyph-property-instance') as an instantiator in place of an
+ actual instantiator. In such a case, the instantiator used to
+ create that instance object will be used (for example, if you set
+ a font-instance object as the value of the `font' property, then
+ the font name used to create that object will be used instead).
+ If some cases, however, doing this conversion does not make sense,
+ and this will be noted in the documentation for particular types
+ of instance objects.
+
+ If PROPERTY is not a built-in property, then this function will
+ simply set its value if LOCALE is `nil'. However, if LOCALE is
+ given, then this function will attempt to add VALUE as the
+ instantiator for the given LOCALE, using `add-spec-to-specifier'.
+ If the value of the property is not a specifier, it will
+ automatically be converted into a `generic' specifier.
+
+ - Function: glyph-property glyph property &optional locale
+ This function returns GLYPH's value of the given PROPERTY.
+
+ If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
+ be returned. For built-in properties, this will be a specifier
+ object of a type appropriate to the property (e.g. a font or color
+ specifier). For other properties, this could be anything.
+
+ If LOCALE is supplied, then instead of returning the actual value,
+ the specification(s) for the given locale or locale type will be
+ returned. This will only work if the actual value of PROPERTY is
+ a specifier (this will always be the case for built-in properties,
+ but may or may not apply to user-defined properties). If the
+ actual value of PROPERTY is not a specifier, this value will
+ simply be returned regardless of LOCALE.
+
+ The return value will be a list of instantiators (e.g. vectors
+ specifying pixmap data), or a list of specifications, each of
+ which is a cons of a locale and a list of instantiators.
+ Specifically, if LOCALE is a particular locale (a buffer, window,
+ frame, device, or `global'), a list of instantiators for that
+ locale will be returned. Otherwise, if LOCALE is a locale type
+ (one of the symbols `buffer', `window', `frame', or `device'), the
+ specifications for all locales of that type will be returned.
+ Finally, if LOCALE is `all', the specifications for all locales of
+ all types will be returned.
+
+ The specifications in a specifier determine what the value of
+ PROPERTY will be in a particular "domain" or set of circumstances,
+ which is typically a particular Emacs window along with the buffer
+ it contains and the frame and device it lies within. The value is
+ derived from the instantiator associated with the most specific
+ locale (in the order buffer, window, frame, device, and `global')
+ that matches the domain in question. In other words, given a
+ domain (i.e. an Emacs window, usually), the specifier for PROPERTY
+ will first be searched for a specification whose locale is the
+ buffer contained within that window; then for a specification
+ whose locale is the window itself; then for a specification whose
+ locale is the frame that the window is contained within; etc. The
+ first instantiator that is valid for the domain (usually this
+ means that the instantiator is recognized by the device [i.e. the
+ X server or TTY device] that the domain is on). The function
+ `glyph-property-instance' actually does all this, and is used to
+ determine how to display the glyph.
+
+ - Function: glyph-property-instance glyph property &optional domain
+ default no-fallback
+ This function returns the instance of GLYPH's PROPERTY in the
+ specified DOMAIN.
+
+ Under most circumstances, DOMAIN will be a particular window, and
+ the returned instance describes how the specified property
+ actually is displayed for that window and the particular buffer in
+ it. Note that this may not be the same as how the property
+ appears when the buffer is displayed in a different window or
+ frame, or how the property appears in the same window if you
+ switch to another buffer in that window; and in those cases, the
+ returned instance would be different.
+
+ The returned instance is an image-instance object, and you can
+ query it using the appropriate image instance functions. For
+ example, you could use `image-instance-depth' to find out the
+ depth (number of color planes) of a pixmap displayed in a
+ particular window. The results might be different from the
+ results you would get for another window (perhaps the user
+ specified a different image for the frame that window is on; or
+ perhaps the same image was specified but the window is on a
+ different X server, and that X server has different color
+ capabilities from this one).
+
+ DOMAIN defaults to the selected window if omitted.
+
+ DOMAIN can be a frame or device, instead of a window. The value
+ returned for such a domain is used in special circumstances when a
+ more specific domain does not apply; for example, a frame value
+ might be used for coloring a toolbar, which is conceptually
+ attached to a frame rather than a particular window. The value is
+ also useful in determining what the value would be for a
+ particular window within the frame or device, if it is not
+ overridden by a more specific specification.
+
+ If PROPERTY does not name a built-in property, its value will
+ simply be returned unless it is a specifier object, in which case
+ it will be instanced using `specifier-instance'.
+
+ Optional arguments DEFAULT and NO-FALLBACK are the same as in
+ `specifier-instance'. *Note Specifiers::.
+
+ - Function: remove-glyph-property glyph property &optional locale
+ tag-set exact-p
+ This function removes a property from a glyph. For built-in
+ properties, this is analogous to `remove-specifier'. *Note
+ remove-specifier-p: Specifiers, for the meaning of the LOCALE,
+ TAG-SET, and EXACT-P arguments.
+
+\1f
+File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
+
+Glyph Convenience Functions
+---------------------------
+
+ The following functions are provided for working with specific
+properties of a glyph. Note that these are exactly like calling the
+general functions described above and passing in the appropriate value
+for PROPERTY.
+
+ Remember that if you want to determine the "value" of a specific
+glyph property, you probably want to use the `*-instance' functions.
+For example, to determine whether a glyph contributes to its line
+height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
+latter will return a boolean specifier or a list of specifications, and
+you probably aren't concerned with these.)
+
+ - Function: glyph-image glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `image'. The return value will be an image specifier
+ if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
+
+ - Function: set-glyph-image glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `image'.
+
+ - Function: glyph-image-instance glyph &optional domain default
+ no-fallback
+ This function returns the instance of GLYPH's image in the given
+ DOMAIN, and is equivalent to calling `glyph-property-instance'
+ with a property of `image'. The return value will be an image
+ instance.
+
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing how the image appears
+ in that particular window and buffer will be returned.
+
+ - Function: glyph-contrib-p glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `contrib-p'. The return value will be a boolean
+ specifier if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
+
+ - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `contrib-p'.
+
+ - Function: glyph-contrib-p-instance glyph &optional domain default
+ no-fallback
+ This function returns whether the glyph contributes to its line
+ height in the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `contrib-p'. The
+ return value will be either `nil' or `t'. (Normally DOMAIN will be
+ a window or `nil', meaning the selected window.)
+
+ - Function: glyph-baseline glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `baseline'. The return value will be a specifier if
+ LOCALE is `nil' or omitted; otherwise, it will be a specification
+ or list of specifications.
+
+ - Function: set-glyph-baseline glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `baseline'.
+
+ - Function: glyph-baseline-instance glyph &optional domain default
+ no-fallback
+ This function returns the instance of GLYPH's baseline value in
+ the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `baseline'. The
+ return value will be an integer or `nil'.
+
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing the baseline value
+ appears in that particular window and buffer will be returned.
+
+ - Function: glyph-face glyph
+ This function returns the face of GLYPH. (Remember, this is not a
+ specifier, but a simple property.)
+
+ - Function: set-glyph-face glyph face
+ This function changes the face of GLYPH to FACE.
+
+\1f
+File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
+
+Glyph Dimensions
+----------------
+
+ - Function: glyph-width glyph &optional window
+ This function returns the width of GLYPH on WINDOW. This may not
+ be exact as it does not take into account all of the context that
+ redisplay will.
+
+ - Function: glyph-ascent glyph &optional window
+ This function returns the ascent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
+
+ - Function: glyph-descent glyph &optional window
+ This function returns the descent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
+
+ - Function: glyph-height glyph &optional window
+ This function returns the height of GLYPH on WINDOW. (This is
+ equivalent to the sum of the ascent and descent values.) This may
+ not be exact as it does not take into account all of the context
+ that redisplay will.
+
+\1f
+File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
+
+Images
+======
+
+* Menu:
+
+* Image Specifiers:: Specifying how an image will appear.
+* Image Instantiator Conversion::
+ Conversion is applied to image instantiators
+ at the time they are added to an
+ image specifier or at the time they
+ are passed to `make-image-instance'.
+* Image Instances:: What an image specifier gets instanced as.
+
+\1f
File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
Image Specifiers
keyword-value pairs. The "format" field should be a symbol, one of
`nothing'
- (Don't display anything; no keywords are valid for this. Can only
- be instanced as `nothing'.)
+ Don't display anything; no keywords are valid for this. Can only
+ be instanced as `nothing'.
`string'
- (Display this image as a text string. Can only be instanced as
+ Display this image as a text string. Can only be instanced as
`text', although support for instancing as `mono-pixmap' should be
- added.)
+ added.
`formatted-string'
- (Display this image as a text string with replaceable fields,
- similar to a modeline format string; not currently implemented.)
+ Display this image as a text string with replaceable fields,
+ similar to a modeline format string; not currently implemented.
`xbm'
- (An X bitmap; only if X support was compiled into this XEmacs.
- Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
+ An X bitmap; only if X support was compiled into this XEmacs. Can
+ be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
`xpm'
- (An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ An XPM pixmap; only if XPM support was compiled into this XEmacs.
Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
XPM is an add-on library for X that was designed to rectify the
shortcomings of the XBM format. Most implementations of X include
the XPM library as a standard part. If your vendor does not, it
is highly recommended that you download it and install it. You
- can get it from the standard XEmacs FTP site, among other places.)
+ can get it from the standard XEmacs FTP site, among other places.
`xface'
- (An X-Face bitmap, used to encode people's faces in e-mail
- messages; only if X-Face support was compiled into this XEmacs.
- Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
+ An X-Face bitmap, used to encode people's faces in e-mail messages;
+ only if X-Face support was compiled into this XEmacs. Can be
+ instanced as `mono-pixmap', `color-pixmap', or `pointer'.
`gif'
- (A GIF87 or GIF89 image; only if GIF support was compiled into this
+ A GIF87 or GIF89 image; only if GIF support was compiled into this
XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
includes GIF decoding functions as a standard part of it, so if
you have X support, you will normally have GIF support, unless you
- explicitly disable it at configure time.)
+ explicitly disable it at configure time.
`jpeg'
- (A JPEG-format image; only if JPEG support was compiled into this
+ A JPEG-format image; only if JPEG support was compiled into this
XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
libraries present on your system when XEmacs is built, XEmacs will
automatically detect this and use them, unless you explicitly
- disable it at configure time.)
+ disable it at configure time.
`png'
- (A PNG/GIF24 image; only if PNG support was compiled into this
- XEmacs. Can be instanced as `color-pixmap'.)
+ A PNG/GIF24 image; only if PNG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'.
`tiff'
- (A TIFF-format image; only if TIFF support was compiled into this
- XEmacs. Not currently implemented.)
+ A TIFF-format image; only if TIFF support was compiled into this
+ XEmacs.
`cursor-font'
- (One of the standard cursor-font names, such as `watch' or
+ One of the standard cursor-font names, such as `watch' or
`right_ptr' under X. Under X, this is, more specifically, any of
the standard cursor names from appendix B of the Xlib manual [also
known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
other window systems, the valid names will be specific to the type
- of window system. Can only be instanced as `pointer'.)
+ of window system. Can only be instanced as `pointer'.
`font'
- (A glyph from a font; i.e. the name of a font, and glyph index
- into it of the form `FONT fontname index [[mask-font] mask-index]'.
+ A glyph from a font; i.e. the name of a font, and glyph index into
+ it of the form `FONT fontname index [[mask-font] mask-index]'.
Only if X support was compiled into this XEmacs. Currently can
only be instanced as `pointer', although this should probably be
- fixed.)
+ fixed.
`subwindow'
- (An embedded X window; not currently implemented.)
+ An embedded X window; not currently implemented.
`autodetect'
- (XEmacs tries to guess what format the data is in. If X support
+ XEmacs tries to guess what format the data is in. If X support
exists, the data string will be checked to see if it names a
filename. If so, and this filename contains XBM or XPM data, the
appropriate sort of pixmap or pointer will be created. [This
image-instance types and the string names a valid cursor-font
name, the image will be created as a pointer. Otherwise, the
image will be displayed as text. If no X support exists, the
- image will always be displayed as text.)
+ image will always be displayed as text.
The valid keywords are:
`:data'
- (Inline data. For most formats above, this should be a string.
- For XBM images, this should be a list of three elements: width,
+ Inline data. For most formats above, this should be a string. For
+ XBM images, this should be a list of three elements: width,
height, and a string of bit data. This keyword is not valid for
- instantiator format `nothing'.)
+ instantiator format `nothing'.
`:file'
- (Data is contained in a file. The value is the name of this file.
+ Data is contained in a file. The value is the name of this file.
If both `:data' and `:file' are specified, the image is created
from what is specified in `:data' and the string in `:file'
becomes the value of the `image-instance-file-name' function when
applied to the resulting image-instance. This keyword is not
valid for instantiator formats `nothing', `string',
- `formatted-string', `cursor-font', `font', and `autodetect'.)
+ `formatted-string', `cursor-font', `font', and `autodetect'.
`:foreground'
`:background'
- (For `xbm', `xface', `cursor-font', and `font'. These keywords
+ For `xbm', `xface', `cursor-font', and `font'. These keywords
allow you to explicitly specify foreground and background colors.
The argument should be anything acceptable to
`make-color-instance'. This will cause what would be a
`mono-pixmap' to instead be colorized as a two-color color-pixmap,
and specifies the foreground and/or background colors for a pointer
- instead of black and white.)
+ instead of black and white.
`:mask-data'
- (For `xbm' and `xface'. This specifies a mask to be used with the
+ For `xbm' and `xface'. This specifies a mask to be used with the
bitmap. The format is a list of width, height, and bits, like for
- `:data'.)
+ `:data'.
`:mask-file'
- (For `xbm' and `xface'. This specifies a file containing the mask
+ For `xbm' and `xface'. This specifies a file containing the mask
data. If neither a mask file nor inline mask data is given for an
XBM image, and the XBM image comes from a file, XEmacs will look
for a mask file with the same name as the image file but with
`Mask' or `msk' appended. For example, if you specify the XBM file
`left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
- associated mask file `left_ptrmsk' will automatically be picked
- up.)
+ associated mask file `left_ptrmsk' will automatically be picked up.
`:hotspot-x'
`:hotspot-y'
- (For `xbm' and `xface'. These keywords specify a hotspot if the
+ For `xbm' and `xface'. These keywords specify a hotspot if the
image is instantiated as a `pointer'. Note that if the XBM image
file specifies a hotspot, it will automatically be picked up if no
- explicit hotspot is given.)
+ explicit hotspot is given.
`:color-symbols'
- (Only for `xpm'. This specifies an alist that maps strings that
+ Only for `xpm'. This specifies an alist that maps strings that
specify symbolic color names to the actual color to be used for
that symbolic color (in the form of a string or a color-specifier
object). If this is not specified, the contents of
- `xpm-color-symbols' are used to generate the alist.)
+ `xpm-color-symbols' are used to generate the alist.
If instead of a vector, the instantiator is a string, it will be
converted into a vector by looking it up according to the specs in the
* Annotation Hooks:: Hooks called at certain times during an
annotation's lifetime.
-\1f
-File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
-
-Annotation Basics
-=================
-
- Marginal annotations are notes associated with a particular location
-in a buffer. They may be displayed in a margin created on the
-left-hand or right-hand side of the frame, in any whitespace at the
-beginning or end of a line, or inside of the text itself. Every
-annotation may have an associated action to be performed when the
-annotation is selected. The term "annotation" is used to refer to an
-individual note. The term "margin" is generically used to refer to the
-whitespace before the first character on a line or after the last
-character on a line.
-
- Each annotation has the following characteristics:
-GLYPH
- This is a glyph object and is used as the displayed representation
- of the annotation.
-
-DOWN-GLYPH
- If given, this glyph is used as the displayed representation of
- the annotation when the mouse is pressed down over the annotation.
-
-FACE
- The face with which to display the glyph.
-
-SIDE
- Which side of the text (left or right) the annotation is displayed
- at.
-
-ACTION
- If non-`nil', this field must contain a function capable of being
- the first argument to `funcall'. This function is normally
- evaluated with a single argument, the value of the DATA field,
- each time the annotation is selected. However, if the WITH-EVENT
- parameter to `make-annotation' is non-`nil', the function is
- called with two arguments. The first argument is the same as
- before, and the second argument is the event (a button-up event,
- usually) that activated the annotation.
-
-DATA
- Not used internally. This field can contain any E-Lisp object.
- It is passed as the first argument to ACTION described above.
-
-MENU
- A menu displayed when the right mouse button is pressed over the
- annotation.
-
- The margin is divided into "outside" and "inside". The outside
-margin is space on the left or right side of the frame which normal text
-cannot be displayed in. The inside margin is that space between the
-leftmost or rightmost point at which text can be displayed and where the
-first or last character actually is.
-
- There are four different "layout types" which affect the exact
-location an annotation appears.
-
-`outside-margin'
- The annotation is placed in the outside margin area. as close as
- possible to the edge of the frame. If the outside margin is not
- wide enough for an annotation to fit, it is not displayed.
-
-`inside-margin'
- The annotation is placed in the inside margin area, as close as
- possible to the edge of the frame. If the inside margin is not
- wide enough for the annotation to fit, it will be displayed using
- any available outside margin space if and only if the specifier
- `use-left-overflow' or `use-right-overflow' (depending on which
- side the annotation appears in) is non-`nil'.
-
-`whitespace'
- The annotation is placed in the inside margin area, as close as
- possible to the first or last non-whitespace character on a line.
- If the inside margin is not wide enough for the annotation to fit,
- it will be displayed if and only if the specifier
- `use-left-overflow' or `use-right-overflow' (depending on which
- side the annotation appears in) is non-`nil'.
-
-`text'
- The annotation is placed at the position it is inserted. It will
- create enough space for itself inside of the text area. It does
- not take up a place in the logical buffer, only in the display of
- the buffer.
-
- The current layout policy is that all `whitespace' annotations are
-displayed first. Next, all `inside-margin' annotations are displayed
-using any remaining space. Finally as many `outside-margin'
-annotations are displayed as possible. The `text' annotations will
-always display as they create their own space to display in.
-
-\1f
-File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
-
-Annotation Primitives
-=====================
-
- - Function: make-annotation glyph &optional position layout buffer
- with-event d-glyph rightp
- This function creates a marginal annotation at position POS in
- BUFFER. The annotation is displayed using GLYPH, which should be
- a glyph object or a string, and is positioned using layout policy
- LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil',
- `whitespace' is used. If BUFFER is `nil', the current buffer is
- used.
-
- If WITH-EVENT is non-`nil', then when an annotation is activated,
- the triggering event is passed as the second arg to the annotation
- function. If D-GLYPH is non-`nil' then it is used as the glyph
- that will be displayed when button1 is down. If RIGHTP is
- non-`nil' then the glyph will be displayed on the right side of
- the buffer instead of the left.
-
- The newly created annotation is returned.
-
- - Function: delete-annotation annotation
- This function removes ANNOTATION from its buffer. This does not
- modify the buffer text.
-
- - Function: annotationp annotation
- This function returns `t' if ANNOTATION is an annotation, `nil'
- otherwise.
-
-\1f
-File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
-
-Annotation Properties
-=====================
-
- - Function: annotation-glyph annotation
- This function returns the glyph object used to display ANNOTATION.
-
- - Function: set-annotation-glyph annotation glyph &optional layout side
- This function sets the glyph of ANNOTATION to GLYPH, which should
- be a glyph object. If LAYOUT is non-`nil', set the layout policy
- of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
- side of the buffer at which the annotation is displayed to the
- given side. The new value of `annotation-glyph' is returned.
-
- - Function: annotation-down-glyph annotation
- This function returns the glyph used to display ANNOTATION when
- the left mouse button is depressed on the annotation.
-
- - Function: set-annotation-down-glyph annotation glyph
- This function returns the glyph used to display ANNOTATION when
- the left mouse button is depressed on the annotation to GLYPH,
- which should be a glyph object.
-
- - Function: annotation-face annotation
- This function returns the face associated with ANNOTATION.
-
- - Function: set-annotation-face annotation face
- This function sets the face associated with ANNOTATION to FACE.
-
- - Function: annotation-layout annotation
- This function returns the layout policy of ANNOTATION.
-
- - Function: set-annotation-layout annotation layout
- This function sets the layout policy of ANNOTATION to LAYOUT.
-
- - Function: annotation-side annotation
- This function returns the side of the buffer that ANNOTATION is
- displayed on. Return value is a symbol, either `left' or `right'.
-
- - Function: annotation-data annotation
- This function returns the data associated with ANNOTATION.
-
- - Function: set-annotation-data annotation data
- This function sets the data field of ANNOTATION to DATA. DATA is
- returned.
-
- - Function: annotation-action annotation
- This function returns the action associated with ANNOTATION.
-
- - Function: set-annotation-action annotation action
- This function sets the action field of ANNOTATION to ACTION.
- ACTION is returned..
-
- - Function: annotation-menu annotation
- This function returns the menu associated with ANNOTATION.
-
- - Function: set-annotation-menu annotation menu
- This function sets the menu associated with ANNOTATION to MENU.
- This menu will be displayed when the right mouse button is pressed
- over the annotation.
-
- - Function: annotation-visible annotation
- This function returns `t' if there is enough available space to
- display ANNOTATION, `nil' otherwise.
-
- - Function: annotation-width annotation
- This function returns the width of ANNOTATION in pixels.
-
- - Function: hide-annotation annotation
- This function removes ANNOTATION's glyph, making it invisible.
-
- - Function: reveal-annotation annotation
- This function restores ANNOTATION's glyph, making it visible.
-
-\1f
-File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
-
-Locating Annotations
-====================
-
- - Function: annotations-in-region start end buffer
- This function returns a list of all annotations in BUFFER which
- are between START and END inclusively.
-
- - Function: annotations-at &optional position buffer
- This function returns a list of all annotations at POSITION in
- BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
- the current buffer is used.
-
- - Function: annotation-list &optional buffer
- This function returns a list of all annotations in BUFFER. If
- BUFFER is `nil', the current buffer is used.
-
- - Function: all-annotations
- This function returns a list of all annotations in all buffers in
- existence.
-
-\1f
-File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
-
-Margin Primitives
-=================
-
- The margin widths are controllable on a buffer-local, window-local,
-frame-local, device-local, or device-type-local basis through the use
-of specifiers. *Note Specifiers::.
-
- - Specifier: left-margin-width
- This is a specifier variable controlling the width of the left
- outside margin, in characters. Use `set-specifier' to change its
- value.
-
- - Specifier: right-margin-width
- This is a specifier variable controlling the width of the right
- outside margin, in characters. Use `set-specifier' to change its
- value.
-
- - Specifier: use-left-overflow
- If non-`nil', use the left outside margin as extra whitespace when
- displaying `whitespace' and `inside-margin' annotations. Defaults
- to `nil'. This is a specifier variable; use `set-specifier' to
- change its value.
-
- - Specifier: use-right-overflow
- If non-`nil', use the right outside margin as extra whitespace when
- displaying `whitespace' and `inside-margin' annotations. Defaults
- to `nil'. This is a specifier variable; use `set-specifier' to
- change its value.
-
- - Function: window-left-margin-pixel-width &optional window
- This function returns the width in pixels of the left outside
- margin of WINDOW. If WINDOW is `nil', the selected window is
- assumed.
-
- - Function: window-right-margin-pixel-width &optional window
- This function returns the width in pixels of the right outside
- margin of WINDOW. If WINDOW is `nil', the selected window is
- assumed.
-
- The margin colors are controlled by the faces `left-margin' and
-`right-margin'. These can be set using the X resources
-`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
-likewise for the right margin.
-
-\1f
-File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
-
-Annotation Hooks
-================
-
- The following three hooks are provided for use with the marginal
-annotations:
-
-`before-delete-annotation-hook'
- This hook is called immediately before an annotation is destroyed.
- It is passed a single argument, the annotation being destroyed.
-
-`after-delete-annotation-hook'
- This normal hook is called immediately after an annotation is
- destroyed.
-
-`make-annotation-hook'
- This hook is called immediately after an annotation is created.
- It is passed a single argument, the newly created annotation.
-
-\1f
-File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
-
-Emacs Display
-*************
-
- This chapter describes a number of other features related to the
-display that XEmacs presents to the user.
-
-* Menu:
-
-* Refresh Screen:: Clearing the screen and redrawing everything on it.
-* Truncation:: Folding or wrapping long text lines.
-* The Echo Area:: Where messages are displayed.
-* Warnings:: Display of Warnings.
-* Invisible Text:: Hiding part of the buffer text.
-* Selective Display:: Hiding part of the buffer text (the old way).
-* Overlay Arrow:: Display of an arrow to indicate position.
-* Temporary Displays:: Displays that go away automatically.
-* Blinking:: How XEmacs shows the matching open parenthesis.
-* Usual Display:: The usual conventions for displaying nonprinting chars.
-* Display Tables:: How to specify other conventions.
-* Beeping:: Audible signal to the user.
-
-\1f
-File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
-
-Refreshing the Screen
-=====================
-
- The function `redraw-frame' redisplays the entire contents of a
-given frame. *Note Frames::.
-
- - Function: redraw-frame frame
- This function clears and redisplays frame FRAME.
-
- Even more powerful is `redraw-display':
-
- - Command: redraw-display &optional device
- This function redraws all frames on DEVICE marked as having their
- image garbled. DEVICE defaults to the selected device. If DEVICE
- is `t', all devices will have their frames checked.
-
- Processing user input takes absolute priority over redisplay. If you
-call these functions when input is available, they do nothing
-immediately, but a full redisplay does happen eventually--after all the
-input has been processed.
-
- Normally, suspending and resuming XEmacs also refreshes the screen.
-Some terminal emulators record separate contents for display-oriented
-programs such as XEmacs and for ordinary sequential display. If you are
-using such a terminal, you might want to inhibit the redisplay on
-resumption. *Note Suspending XEmacs::.
-
- - Variable: no-redraw-on-reenter
- This variable controls whether XEmacs redraws the entire screen
- after it has been suspended and resumed. Non-`nil' means yes,
- `nil' means no.
-
- The above functions do not actually cause the display to be updated;
-rather, they clear out the internal display records that XEmacs
-maintains, so that the next time the display is updated it will be
-redrawn from scratch. Normally this occurs the next time that
-`next-event' or `sit-for' is called; however, a display update will not
-occur if there is input pending. *Note Command Loop::.
-
- - Function: force-cursor-redisplay
- This function causes an immediate update of the cursor on the
- selected frame. (This function does not exist in FSF Emacs.)
-
-\1f
-File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
-
-Truncation
-==========
-
- When a line of text extends beyond the right edge of a window, the
-line can either be truncated or continued on the next line. When a line
-is truncated, this is normally shown with a `\' in the rightmost column
-of the window on X displays, and with a `$' on TTY devices. When a
-line is continued or "wrapped" onto the next line, this is shown with a
-curved arrow in the rightmost column of the window (or with a `\' on
-TTY devices). The additional screen lines used to display a long text
-line are called "continuation" lines.
-
- Normally, whenever line truncation is in effect for a particular
-window, a horizontal scrollbar is displayed in that window if the
-device supports scrollbars. *Note Scrollbars::.
-
- Note that continuation is different from filling; continuation
-happens on the screen only, not in the buffer contents, and it breaks a
-line precisely at the right margin, not at a word boundary. *Note
-Filling::.
-
- - User Option: truncate-lines
- This buffer-local variable controls how XEmacs displays lines that
- extend beyond the right edge of the window. If it is non-`nil',
- then XEmacs does not display continuation lines; rather each line
- of text occupies exactly one screen line, and a backslash appears
- at the edge of any line that extends to or beyond the edge of the
- window. The default is `nil'.
-
- If the variable `truncate-partial-width-windows' is non-`nil',
- then truncation is always used for side-by-side windows (within one
- frame) regardless of the value of `truncate-lines'.
-
- - User Option: default-truncate-lines
- This variable is the default value for `truncate-lines', for
- buffers that do not have local values for it.
-
- - User Option: truncate-partial-width-windows
- This variable controls display of lines that extend beyond the
- right edge of the window, in side-by-side windows (*note Splitting
- Windows::). If it is non-`nil', these lines are truncated;
- otherwise, `truncate-lines' says what to do with them.
-
- The backslash and curved arrow used to indicate truncated or
-continued lines are only defaults, and can be changed. These images
-are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
-flexibility in how glyphs can be controlled. (This differs from FSF
-Emacs, which uses display tables to control these images.)
-
- For details, *Note Redisplay Glyphs::.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
+
+Annotation Basics
+=================
+
+ Marginal annotations are notes associated with a particular location
+in a buffer. They may be displayed in a margin created on the
+left-hand or right-hand side of the frame, in any whitespace at the
+beginning or end of a line, or inside of the text itself. Every
+annotation may have an associated action to be performed when the
+annotation is selected. The term "annotation" is used to refer to an
+individual note. The term "margin" is generically used to refer to the
+whitespace before the first character on a line or after the last
+character on a line.
+
+ Each annotation has the following characteristics:
+GLYPH
+ This is a glyph object and is used as the displayed representation
+ of the annotation.
+
+DOWN-GLYPH
+ If given, this glyph is used as the displayed representation of
+ the annotation when the mouse is pressed down over the annotation.
+
+FACE
+ The face with which to display the glyph.
+
+SIDE
+ Which side of the text (left or right) the annotation is displayed
+ at.
+
+ACTION
+ If non-`nil', this field must contain a function capable of being
+ the first argument to `funcall'. This function is normally
+ evaluated with a single argument, the value of the DATA field,
+ each time the annotation is selected. However, if the WITH-EVENT
+ parameter to `make-annotation' is non-`nil', the function is
+ called with two arguments. The first argument is the same as
+ before, and the second argument is the event (a button-up event,
+ usually) that activated the annotation.
+
+DATA
+ Not used internally. This field can contain any E-Lisp object.
+ It is passed as the first argument to ACTION described above.
+
+MENU
+ A menu displayed when the right mouse button is pressed over the
+ annotation.
+
+ The margin is divided into "outside" and "inside". The outside
+margin is space on the left or right side of the frame which normal text
+cannot be displayed in. The inside margin is that space between the
+leftmost or rightmost point at which text can be displayed and where the
+first or last character actually is.
+
+ There are four different "layout types" which affect the exact
+location an annotation appears.
+
+`outside-margin'
+ The annotation is placed in the outside margin area. as close as
+ possible to the edge of the frame. If the outside margin is not
+ wide enough for an annotation to fit, it is not displayed.
+
+`inside-margin'
+ The annotation is placed in the inside margin area, as close as
+ possible to the edge of the frame. If the inside margin is not
+ wide enough for the annotation to fit, it will be displayed using
+ any available outside margin space if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`whitespace'
+ The annotation is placed in the inside margin area, as close as
+ possible to the first or last non-whitespace character on a line.
+ If the inside margin is not wide enough for the annotation to fit,
+ it will be displayed if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`text'
+ The annotation is placed at the position it is inserted. It will
+ create enough space for itself inside of the text area. It does
+ not take up a place in the logical buffer, only in the display of
+ the buffer.
+
+ The current layout policy is that all `whitespace' annotations are
+displayed first. Next, all `inside-margin' annotations are displayed
+using any remaining space. Finally as many `outside-margin'
+annotations are displayed as possible. The `text' annotations will
+always display as they create their own space to display in.
+
+\1f
+File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
+
+Annotation Primitives
+=====================
+
+ - Function: make-annotation glyph &optional position layout buffer
+ with-event d-glyph rightp
+ This function creates a marginal annotation at position POS in
+ BUFFER. The annotation is displayed using GLYPH, which should be
+ a glyph object or a string, and is positioned using layout policy
+ LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil',
+ `whitespace' is used. If BUFFER is `nil', the current buffer is
+ used.
+
+ If WITH-EVENT is non-`nil', then when an annotation is activated,
+ the triggering event is passed as the second arg to the annotation
+ function. If D-GLYPH is non-`nil' then it is used as the glyph
+ that will be displayed when button1 is down. If RIGHTP is
+ non-`nil' then the glyph will be displayed on the right side of
+ the buffer instead of the left.
+
+ The newly created annotation is returned.
+
+ - Function: delete-annotation annotation
+ This function removes ANNOTATION from its buffer. This does not
+ modify the buffer text.
+
+ - Function: annotationp annotation
+ This function returns `t' if ANNOTATION is an annotation, `nil'
+ otherwise.
+
+\1f
+File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
+
+Annotation Properties
+=====================
+
+ - Function: annotation-glyph annotation
+ This function returns the glyph object used to display ANNOTATION.
+
+ - Function: set-annotation-glyph annotation glyph &optional layout side
+ This function sets the glyph of ANNOTATION to GLYPH, which should
+ be a glyph object. If LAYOUT is non-`nil', set the layout policy
+ of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
+ side of the buffer at which the annotation is displayed to the
+ given side. The new value of `annotation-glyph' is returned.
+
+ - Function: annotation-down-glyph annotation
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation.
+
+ - Function: set-annotation-down-glyph annotation glyph
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation to GLYPH,
+ which should be a glyph object.
+
+ - Function: annotation-face annotation
+ This function returns the face associated with ANNOTATION.
+
+ - Function: set-annotation-face annotation face
+ This function sets the face associated with ANNOTATION to FACE.
+
+ - Function: annotation-layout annotation
+ This function returns the layout policy of ANNOTATION.
+
+ - Function: set-annotation-layout annotation layout
+ This function sets the layout policy of ANNOTATION to LAYOUT.
+
+ - Function: annotation-side annotation
+ This function returns the side of the buffer that ANNOTATION is
+ displayed on. Return value is a symbol, either `left' or `right'.
+
+ - Function: annotation-data annotation
+ This function returns the data associated with ANNOTATION.
+
+ - Function: set-annotation-data annotation data
+ This function sets the data field of ANNOTATION to DATA. DATA is
+ returned.
+
+ - Function: annotation-action annotation
+ This function returns the action associated with ANNOTATION.
+
+ - Function: set-annotation-action annotation action
+ This function sets the action field of ANNOTATION to ACTION.
+ ACTION is returned..
+
+ - Function: annotation-menu annotation
+ This function returns the menu associated with ANNOTATION.
+
+ - Function: set-annotation-menu annotation menu
+ This function sets the menu associated with ANNOTATION to MENU.
+ This menu will be displayed when the right mouse button is pressed
+ over the annotation.
+
+ - Function: annotation-visible annotation
+ This function returns `t' if there is enough available space to
+ display ANNOTATION, `nil' otherwise.
+
+ - Function: annotation-width annotation
+ This function returns the width of ANNOTATION in pixels.
+
+ - Function: hide-annotation annotation
+ This function removes ANNOTATION's glyph, making it invisible.
+
+ - Function: reveal-annotation annotation
+ This function restores ANNOTATION's glyph, making it visible.
+
+\1f
+File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
+
+Locating Annotations
+====================
+
+ - Function: annotations-in-region start end buffer
+ This function returns a list of all annotations in BUFFER which
+ are between START and END inclusively.
+
+ - Function: annotations-at &optional position buffer
+ This function returns a list of all annotations at POSITION in
+ BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
+ the current buffer is used.
+
+ - Function: annotation-list &optional buffer
+ This function returns a list of all annotations in BUFFER. If
+ BUFFER is `nil', the current buffer is used.
+
+ - Function: all-annotations
+ This function returns a list of all annotations in all buffers in
+ existence.
+
+\1f
+File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
+
+Margin Primitives
+=================
+
+ The margin widths are controllable on a buffer-local, window-local,
+frame-local, device-local, or device-type-local basis through the use
+of specifiers. *Note Specifiers::.
+
+ - Specifier: left-margin-width
+ This is a specifier variable controlling the width of the left
+ outside margin, in characters. Use `set-specifier' to change its
+ value.
+
+ - Specifier: right-margin-width
+ This is a specifier variable controlling the width of the right
+ outside margin, in characters. Use `set-specifier' to change its
+ value.
+
+ - Specifier: use-left-overflow
+ If non-`nil', use the left outside margin as extra whitespace when
+ displaying `whitespace' and `inside-margin' annotations. Defaults
+ to `nil'. This is a specifier variable; use `set-specifier' to
+ change its value.
+
+ - Specifier: use-right-overflow
+ If non-`nil', use the right outside margin as extra whitespace when
+ displaying `whitespace' and `inside-margin' annotations. Defaults
+ to `nil'. This is a specifier variable; use `set-specifier' to
+ change its value.
+
+ - Function: window-left-margin-pixel-width &optional window
+ This function returns the width in pixels of the left outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ - Function: window-right-margin-pixel-width &optional window
+ This function returns the width in pixels of the right outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ The margin colors are controlled by the faces `left-margin' and
+`right-margin'. These can be set using the X resources
+`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
+likewise for the right margin.
+
+\1f
+File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
+
+Annotation Hooks
+================
+
+ The following three hooks are provided for use with the marginal
+annotations:
+
+`before-delete-annotation-hook'
+ This hook is called immediately before an annotation is destroyed.
+ It is passed a single argument, the annotation being destroyed.
+
+`after-delete-annotation-hook'
+ This normal hook is called immediately after an annotation is
+ destroyed.
+
+`make-annotation-hook'
+ This hook is called immediately after an annotation is created.
+ It is passed a single argument, the newly created annotation.
+
+\1f
+File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
+
+Emacs Display
+*************
+
+ This chapter describes a number of other features related to the
+display that XEmacs presents to the user.
+
+* Menu:
+
+* Refresh Screen:: Clearing the screen and redrawing everything on it.
+* Truncation:: Folding or wrapping long text lines.
+* The Echo Area:: Where messages are displayed.
+* Warnings:: Display of Warnings.
+* Invisible Text:: Hiding part of the buffer text.
+* Selective Display:: Hiding part of the buffer text (the old way).
+* Overlay Arrow:: Display of an arrow to indicate position.
+* Temporary Displays:: Displays that go away automatically.
+* Blinking:: How XEmacs shows the matching open parenthesis.
+* Usual Display:: The usual conventions for displaying nonprinting chars.
+* Display Tables:: How to specify other conventions.
+* Beeping:: Audible signal to the user.
+
+\1f
+File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
+
+Refreshing the Screen
+=====================
+
+ The function `redraw-frame' redisplays the entire contents of a
+given frame. *Note Frames::.
+
+ - Function: redraw-frame frame
+ This function clears and redisplays frame FRAME.
+
+ Even more powerful is `redraw-display':
+
+ - Command: redraw-display &optional device
+ This function redraws all frames on DEVICE marked as having their
+ image garbled. DEVICE defaults to the selected device. If DEVICE
+ is `t', all devices will have their frames checked.
+
+ Processing user input takes absolute priority over redisplay. If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually--after all the
+input has been processed.
+
+ Normally, suspending and resuming XEmacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as XEmacs and for ordinary sequential display. If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption. *Note Suspending XEmacs::.
+
+ - Variable: no-redraw-on-reenter
+ This variable controls whether XEmacs redraws the entire screen
+ after it has been suspended and resumed. Non-`nil' means yes,
+ `nil' means no.
+
+ The above functions do not actually cause the display to be updated;
+rather, they clear out the internal display records that XEmacs
+maintains, so that the next time the display is updated it will be
+redrawn from scratch. Normally this occurs the next time that
+`next-event' or `sit-for' is called; however, a display update will not
+occur if there is input pending. *Note Command Loop::.
+
+ - Function: force-cursor-redisplay
+ This function causes an immediate update of the cursor on the
+ selected frame. (This function does not exist in FSF Emacs.)
+
+\1f
+File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
+
+Truncation
+==========
+
+ When a line of text extends beyond the right edge of a window, the
+line can either be truncated or continued on the next line. When a line
+is truncated, this is normally shown with a `\' in the rightmost column
+of the window on X displays, and with a `$' on TTY devices. When a
+line is continued or "wrapped" onto the next line, this is shown with a
+curved arrow in the rightmost column of the window (or with a `\' on
+TTY devices). The additional screen lines used to display a long text
+line are called "continuation" lines.
+
+ Normally, whenever line truncation is in effect for a particular
+window, a horizontal scrollbar is displayed in that window if the
+device supports scrollbars. *Note Scrollbars::.
+
+ Note that continuation is different from filling; continuation
+happens on the screen only, not in the buffer contents, and it breaks a
+line precisely at the right margin, not at a word boundary. *Note
+Filling::.
+
+ - User Option: truncate-lines
+ This buffer-local variable controls how XEmacs displays lines that
+ extend beyond the right edge of the window. If it is non-`nil',
+ then XEmacs does not display continuation lines; rather each line
+ of text occupies exactly one screen line, and a backslash appears
+ at the edge of any line that extends to or beyond the edge of the
+ window. The default is `nil'.
+
+ If the variable `truncate-partial-width-windows' is non-`nil',
+ then truncation is always used for side-by-side windows (within one
+ frame) regardless of the value of `truncate-lines'.
+
+ - User Option: default-truncate-lines
+ This variable is the default value for `truncate-lines', for
+ buffers that do not have local values for it.
+
+ - User Option: truncate-partial-width-windows
+ This variable controls display of lines that extend beyond the
+ right edge of the window, in side-by-side windows (*note Splitting
+ Windows::). If it is non-`nil', these lines are truncated;
+ otherwise, `truncate-lines' says what to do with them.
+
+ The backslash and curved arrow used to indicate truncated or
+continued lines are only defaults, and can be changed. These images
+are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
+flexibility in how glyphs can be controlled. (This differs from FSF
+Emacs, which uses display tables to control these images.)
+
+ For details, *Note Redisplay Glyphs::.
+
+\1f
File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
The Echo Area
Display according to the standard interpretation (*note Usual
Display::).
-\1f
-File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
-
-Beeping
-=======
-
- You can make XEmacs ring a bell, play a sound, or blink the screen to
-attract the user's attention. Be conservative about how often you do
-this; frequent bells can become irritating. Also be careful not to use
-beeping alone when signaling an error is appropriate. (*Note Errors::.)
-
- - Function: ding &optional dont-terminate sound device
- This function beeps, or flashes the screen (see `visible-bell'
- below). It also terminates any keyboard macro currently executing
- unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
- should be a symbol specifying which sound to make. This sound
- will be played if `visible-bell' is `nil'. (This only works if
- sound support was compiled into the executable and you are running
- on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
- PC. Otherwise you just get a beep.) The optional third argument
- specifies what device to make the sound on, and defaults to the
- selected device.
-
- - Function: beep &optional dont-terminate sound device
- This is a synonym for `ding'.
-
- - User Option: visible-bell
- This variable determines whether XEmacs should flash the screen to
- represent a bell. Non-`nil' means yes, `nil' means no. On TTY
- devices, this is effective only if the Termcap entry for the
- terminal type has the visible bell flag (`vb') set.
-
- - Variable: sound-alist
- This variable holds an alist associating names with sounds. When
- `beep' or `ding' is called with one of the name symbols, the
- associated sound will be generated instead of the standard beep.
-
- Each element of `sound-alist' is a list describing a sound. The
- first element of the list is the name of the sound being defined.
- Subsequent elements of the list are alternating keyword/value
- pairs:
-
- `sound'
- A string of raw sound data, or the name of another sound to
- play. The symbol `t' here means use the default X beep.
-
- `volume'
- An integer from 0-100, defaulting to `bell-volume'.
-
- `pitch'
- If using the default X beep, the pitch (Hz) to generate.
-
- `duration'
- If using the default X beep, the duration (milliseconds).
-
- For compatibility, elements of `sound-alist' may also be:
-
- * `( sound-name . <sound> )'
-
- * `( sound-name <volume> <sound> )'
-
- You should probably add things to this list by calling the function
- `load-sound-file'.
-
- Caveats:
-
- - You can only play audio data if running on the console screen
- of a Sun SparcStation, SGI, or HP9000s700.
-
- - The pitch, duration, and volume options are available
- everywhere, but many X servers ignore the `pitch' option.
-
- The following beep-types are used by XEmacs itself:
-
- `auto-save-error'
- when an auto-save does not succeed
-
- `command-error'
- when the XEmacs command loop catches an error
-
- `undefined-key'
- when you type a key that is undefined
-
- `undefined-click'
- when you use an undefined mouse-click combination
-
- `no-completion'
- during completing-read
-
- `y-or-n-p'
- when you type something other than 'y' or 'n'
-
- `yes-or-no-p'
- when you type something other than 'yes' or 'no'
-
- `default'
- used when nothing else is appropriate.
-
- Other lisp packages may use other beep types, but these are the
- ones that the C kernel of XEmacs uses.
-
- - User Option: bell-volume
- This variable specifies the default volume for sounds, from 0 to
- 100.
-
- - Command: load-default-sounds
- This function loads and installs some sound files as beep-types.
-
- - Command: load-sound-file filename sound-name &optional volume
- This function reads in an audio file and adds it to `sound-alist'.
- The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
- should be a symbol, specifying the name of the sound. If VOLUME
- is specified, the sound will be played at that volume; otherwise,
- the value of BELL-VOLUME will be used.
-
- - Function: play-sound sound &optional volume device
- This function plays sound SOUND, which should be a symbol
- mentioned in `sound-alist'. If VOLUME is specified, it overrides
- the value (if any) specified in `sound-alist'. DEVICE specifies
- the device to play the sound on, and defaults to the selected
- device.
-
- - Command: play-sound-file file &optional volume device
- This function plays the named sound file at volume VOLUME, which
- defaults to `bell-volume'. DEVICE specifies the device to play
- the sound on, and defaults to the selected device.
-
-\1f
-File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
-
-Hash Tables
-***********
-
- - Function: hash-table-p object
- This function returns `t' if OBJECT is a hash table, else `nil'.
-
-* Menu:
-
-* Introduction to Hash Tables:: Hash tables are fast data structures for
- implementing simple tables (i.e. finite
- mappings from keys to values).
-* Working With Hash Tables:: Hash table functions.
-* Weak Hash Tables:: Hash tables with special garbage-collection
- behavior.
-
-\1f
-File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
-
-Introduction to Hash Tables
-===========================
-
- A "hash table" is a data structure that provides mappings from
-arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
-called "values". A key/value pair is sometimes called an "entry" in
-the hash table. There are many ways other than hash tables of
-implementing the same sort of mapping, e.g. association lists (*note
-Association Lists::) and property lists (*note Property Lists::), but
-hash tables provide much faster lookup when there are many entries in
-the mapping. Hash tables are an implementation of the abstract data
-type "dictionary", also known as "associative array".
-
- Internally, hash tables are hashed using the "linear probing" hash
-table implementation method. This method hashes each key to a
-particular spot in the hash table, and then scans forward sequentially
-until a blank entry is found. To look up a key, hash to the appropriate
-spot, then search forward for the key until either a key is found or a
-blank entry stops the search. This method is used in preference to
-double hashing because of changes in recent hardware. The penalty for
-non-sequential access to memory has been increasing, and this
-compensates for the problem of clustering that linear probing entails.
-
- When hash tables are created, the user may (but is not required to)
-specify initial properties that influence performance.
-
- Use the `:size' parameter to specify the number of entries that are
-likely to be stored in the hash table, to avoid the overhead of resizing
-the table. But if the pre-allocated space for the entries is never
-used, it is simply wasted and makes XEmacs slower. Excess unused hash
-table entries exact a small continuous performance penalty, since they
-must be scanned at every garbage collection. If the number of entries
-in the hash table is unknown, simply avoid using the `:size' keyword.
-
- Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
-the algorithm for deciding when to rehash the hash table. For
-temporary hash tables that are going to be very heavily used, use a
-small rehash threshold, for example, 0.4 and a large rehash size, for
-example 2.0. For permanent hash tables that will be infrequently used,
-specify a large rehash threshold, for example 0.8.
-
- Hash tables can also be created by the lisp reader using structure
-syntax, for example:
- #s(hash-table size 20 data (foo 1 bar 2))
-
- The structure syntax accepts the same keywords as `make-hash-table'
-(without the `:' character), as well as the additional keyword `data',
-which specifies the initial hash table contents.
-
- - Function: make-hash-table &key `test' `size' `rehash-size'
- `rehash-threshold' `weakness'
- This function returns a new empty hash table object.
-
- Keyword `:test' can be `eq', `eql' (default) or `equal'.
- Comparison between keys is done using this function. If speed is
- important, consider using `eq'. When storing strings in the hash
- table, you will likely need to use `equal'.
-
- Keyword `:size' specifies the number of keys likely to be inserted.
- This number of entries can be inserted without enlarging the hash
- table.
-
- Keyword `:rehash-size' must be a float greater than 1.0, and
- specifies the factor by which to increase the size of the hash
- table when enlarging.
-
- Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
- and specifies the load factor of the hash table which triggers
- enlarging.
-
- Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
-
- A weak hash table is one whose pointers do not count as GC
- referents: for any key-value pair in the hash table, if the only
- remaining pointer to either the key or the value is in a weak hash
- table, then the pair will be removed from the hash table, and the
- key and value collected. A non-weak hash table (or any other
- pointer) would prevent the object from being collected.
-
- A key-weak hash table is similar to a fully-weak hash table except
- that a key-value pair will be removed only if the key remains
- unmarked outside of weak hash tables. The pair will remain in the
- hash table if the key is pointed to by something other than a weak
- hash table, even if the value is not.
-
- A value-weak hash table is similar to a fully-weak hash table
- except that a key-value pair will be removed only if the value
- remains unmarked outside of weak hash tables. The pair will
- remain in the hash table if the value is pointed to by something
- other than a weak hash table, even if the key is not.
-
- - Function: copy-hash-table hash-table
- This function returns a new hash table which contains the same
- keys and values as HASH-TABLE. The keys and values will not
- themselves be copied.
-
- - Function: hash-table-count hash-table
- This function returns the number of entries in HASH-TABLE.
-
- - Function: hash-table-test hash-table
- This function returns the test function of HASH-TABLE. This can
- be one of `eq', `eql' or `equal'.
-
- - Function: hash-table-size hash-table
- This function returns the current number of slots in HASH-TABLE,
- whether occupied or not.
-
- - Function: hash-table-rehash-size hash-table
- This function returns the current rehash size of HASH-TABLE. This
- is a float greater than 1.0; the factor by which HASH-TABLE is
- enlarged when the rehash threshold is exceeded.
-
- - Function: hash-table-rehash-threshold hash-table
- This function returns the current rehash threshold of HASH-TABLE.
- This is a float between 0.0 and 1.0; the maximum "load factor" of
- HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
-
- - Function: hash-table-weakness hash-table
- This function returns the weakness of HASH-TABLE. This can be one
- of `nil', `t', `key' or `value'.
-
-\1f
-File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
-
-Working With Hash Tables
-========================
-
- - Function: puthash key value hash-table
- This function hashes KEY to VALUE in HASH-TABLE.
-
- - Function: gethash key hash-table &optional default
- This function finds the hash value for KEY in HASH-TABLE. If
- there is no entry for KEY in HASH-TABLE, DEFAULT is returned
- (which in turn defaults to `nil').
-
- - Function: remhash key hash-table
- This function removes the entry for KEY from HASH-TABLE. Does
- nothing if there is no entry for KEY in HASH-TABLE.
-
- - Function: clrhash hash-table
- This function removes all entries from HASH-TABLE, leaving it
- empty.
-
- - Function: maphash function hash-table
- This function maps FUNCTION over entries in HASH-TABLE, calling it
- with two args, each key and value in the hash table.
-
- FUNCTION may not modify HASH-TABLE, with the one exception that
- FUNCTION may remhash or puthash the entry currently being
- processed by FUNCTION.
-
-\1f
-File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
-
-Weak Hash Tables
-================
-
- A "weak hash table" is a special variety of hash table whose
-elements do not count as GC referents. For any key-value pair in such a
-hash table, if either the key or value (or in some cases, if one
-particular one of the two) has no references to it outside of weak hash
-tables (and similar structures such as weak lists), the pair will be
-removed from the table, and the key and value collected. A non-weak
-hash table (or any other pointer) would prevent the objects from being
-collected.
-
- Weak hash tables are useful for keeping track of information in a
-non-obtrusive way, for example to implement caching. If the cache
-contains objects such as buffers, markers, image instances, etc. that
-will eventually disappear and get garbage-collected, using a weak hash
-table ensures that these objects are collected normally rather than
-remaining around forever, long past their actual period of use.
-(Otherwise, you'd have to explicitly map over the hash table every so
-often and remove unnecessary elements.)
-
- There are three types of weak hash tables:
-
-fully weak hash tables
- In these hash tables, a pair disappears if either the key or the
- value is unreferenced outside of the table.
-
-key-weak hash tables
- In these hash tables, a pair disappears if the key is unreferenced
- outside of the table, regardless of how the value is referenced.
-
-value-weak hash tables
- In these hash tables, a pair disappears if the value is
- unreferenced outside of the table, regardless of how the key is
- referenced.
-
- Also see *Note Weak Lists::.
-
- Weak hash tables are created by specifying the `:weakness' keyword to
-`make-hash-table'.
-
-\1f
-File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
-
-Range Tables
-************
-
- A range table is a table that efficiently associated values with
-ranges of integers.
-
- Note that range tables have a read syntax, like this:
-
- #s(range-table data ((-3 2) foo (5 20) bar))
-
- This maps integers in the range (-3, 2) to `foo' and integers in the
-range (5, 20) to `bar'.
-
- - Function: range-table-p object
- Return non-`nil' if OBJECT is a range table.
-
-* Menu:
-
-* Introduction to Range Tables:: Range tables efficiently map ranges of
- integers to values.
-* Working With Range Tables:: Range table functions.
-
-\1f
-File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
-
-Introduction to Range Tables
-============================
-
- - Function: make-range-table
- Make a new, empty range table.
-
- - Function: copy-range-table old-table
- Make a new range table which contains the same values for the same
- ranges as the given table. The values will not themselves be
- copied.
-
-\1f
-File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
-
-Working With Range Tables
-=========================
-
- - Function: get-range-table pos table &optional default
- This function finds value for position POS in TABLE. If there is
- no corresponding value, return DEFAULT (defaults to `nil').
-
- - Function: put-range-table start end val table
- This function sets the value for range (START, END) to be VAL in
- TABLE.
-
- - Function: remove-range-table start end table
- This function removes the value for range (START, END) in TABLE.
-
- - Function: clear-range-table table
- This function flushes TABLE.
-
- - Function: map-range-table function table
- This function maps FUNCTION over entries in TABLE, calling it with
- three args, the beginning and end of the range and the
- corresponding value.
-
-\1f
-File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
-
-Databases
-*********
-
- - Function: databasep object
- This function returns non-`nil' if OBJECT is a database.
-
-* Menu:
-
-* Connecting to a Database::
-* Working With a Database::
-* Other Database Functions::
-
-\1f
-File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
-
-Connecting to a Database
-========================
-
- - Function: open-database file &optional type subtype access mode
- This function opens database FILE, using database method TYPE and
- SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
- can be any combination of `r' `w' and `+', for read, write, and
- creation flags.
-
- TYPE can have the value `'dbm' or `'berkeley_db' to select the
- type of database file to use. (Note: XEmacs may not support both
- of these types.)
-
- For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should by
- `nil'.
-
- For a TYPE of `'berkeley_db', the following subtypes are
- available: `'hash', `'btree', and `'recno'. See the manpages for
- the Berkeley DB functions to more information about these types.
-
- - Function: close-database obj
- This function closes database OBJ.
-
- - Function: database-live-p obj
- This function returns `t' iff OBJ is an active database, else
- `nil'.
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
+
+Beeping
+=======
+
+ You can make XEmacs ring a bell, play a sound, or blink the screen to
+attract the user's attention. Be conservative about how often you do
+this; frequent bells can become irritating. Also be careful not to use
+beeping alone when signaling an error is appropriate. (*Note Errors::.)
+
+ - Function: ding &optional dont-terminate sound device
+ This function beeps, or flashes the screen (see `visible-bell'
+ below). It also terminates any keyboard macro currently executing
+ unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
+ should be a symbol specifying which sound to make. This sound
+ will be played if `visible-bell' is `nil'. (This only works if
+ sound support was compiled into the executable and you are running
+ on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+ PC. Otherwise you just get a beep.) The optional third argument
+ specifies what device to make the sound on, and defaults to the
+ selected device.
+
+ - Function: beep &optional dont-terminate sound device
+ This is a synonym for `ding'.
+
+ - User Option: visible-bell
+ This variable determines whether XEmacs should flash the screen to
+ represent a bell. Non-`nil' means yes, `nil' means no. On TTY
+ devices, this is effective only if the Termcap entry for the
+ terminal type has the visible bell flag (`vb') set.
+
+ - Variable: sound-alist
+ This variable holds an alist associating names with sounds. When
+ `beep' or `ding' is called with one of the name symbols, the
+ associated sound will be generated instead of the standard beep.
+
+ Each element of `sound-alist' is a list describing a sound. The
+ first element of the list is the name of the sound being defined.
+ Subsequent elements of the list are alternating keyword/value
+ pairs:
+
+ `sound'
+ A string of raw sound data, or the name of another sound to
+ play. The symbol `t' here means use the default X beep.
+
+ `volume'
+ An integer from 0-100, defaulting to `bell-volume'.
+
+ `pitch'
+ If using the default X beep, the pitch (Hz) to generate.
+
+ `duration'
+ If using the default X beep, the duration (milliseconds).
+
+ For compatibility, elements of `sound-alist' may also be:
+
+ * `( sound-name . <sound> )'
+
+ * `( sound-name <volume> <sound> )'
+
+ You should probably add things to this list by calling the function
+ `load-sound-file'.
+
+ Caveats:
+
+ - You can only play audio data if running on the console screen
+ of a Sun SparcStation, SGI, or HP9000s700.
+
+ - The pitch, duration, and volume options are available
+ everywhere, but many X servers ignore the `pitch' option.
+
+ The following beep-types are used by XEmacs itself:
+
+ `auto-save-error'
+ when an auto-save does not succeed
+
+ `command-error'
+ when the XEmacs command loop catches an error
+
+ `undefined-key'
+ when you type a key that is undefined
+
+ `undefined-click'
+ when you use an undefined mouse-click combination
+
+ `no-completion'
+ during completing-read
+
+ `y-or-n-p'
+ when you type something other than 'y' or 'n'
+
+ `yes-or-no-p'
+ when you type something other than 'yes' or 'no'
+
+ `default'
+ used when nothing else is appropriate.
+
+ Other lisp packages may use other beep types, but these are the
+ ones that the C kernel of XEmacs uses.
+
+ - User Option: bell-volume
+ This variable specifies the default volume for sounds, from 0 to
+ 100.
+
+ - Command: load-default-sounds
+ This function loads and installs some sound files as beep-types.
+
+ - Command: load-sound-file filename sound-name &optional volume
+ This function reads in an audio file and adds it to `sound-alist'.
+ The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
+ should be a symbol, specifying the name of the sound. If VOLUME
+ is specified, the sound will be played at that volume; otherwise,
+ the value of BELL-VOLUME will be used.
+
+ - Function: play-sound sound &optional volume device
+ This function plays sound SOUND, which should be a symbol
+ mentioned in `sound-alist'. If VOLUME is specified, it overrides
+ the value (if any) specified in `sound-alist'. DEVICE specifies
+ the device to play the sound on, and defaults to the selected
+ device.
+
+ - Command: play-sound-file file &optional volume device
+ This function plays the named sound file at volume VOLUME, which
+ defaults to `bell-volume'. DEVICE specifies the device to play
+ the sound on, and defaults to the selected device.
+
+\1f
+File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
+
+Hash Tables
+***********
+
+ - Function: hash-table-p object
+ This function returns `t' if OBJECT is a hash table, else `nil'.
+
+* Menu:
+
+* Introduction to Hash Tables:: Hash tables are fast data structures for
+ implementing simple tables (i.e. finite
+ mappings from keys to values).
+* Working With Hash Tables:: Hash table functions.
+* Weak Hash Tables:: Hash tables with special garbage-collection
+ behavior.
+
+\1f
+File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
+
+Introduction to Hash Tables
+===========================
+
+ A "hash table" is a data structure that provides mappings from
+arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
+called "values". A key/value pair is sometimes called an "entry" in
+the hash table. There are many ways other than hash tables of
+implementing the same sort of mapping, e.g. association lists (*note
+Association Lists::) and property lists (*note Property Lists::), but
+hash tables provide much faster lookup when there are many entries in
+the mapping. Hash tables are an implementation of the abstract data
+type "dictionary", also known as "associative array".
+
+ Internally, hash tables are hashed using the "linear probing" hash
+table implementation method. This method hashes each key to a
+particular spot in the hash table, and then scans forward sequentially
+until a blank entry is found. To look up a key, hash to the appropriate
+spot, then search forward for the key until either a key is found or a
+blank entry stops the search. This method is used in preference to
+double hashing because of changes in recent hardware. The penalty for
+non-sequential access to memory has been increasing, and this
+compensates for the problem of clustering that linear probing entails.
+
+ When hash tables are created, the user may (but is not required to)
+specify initial properties that influence performance.
+
+ Use the `:size' parameter to specify the number of entries that are
+likely to be stored in the hash table, to avoid the overhead of resizing
+the table. But if the pre-allocated space for the entries is never
+used, it is simply wasted and makes XEmacs slower. Excess unused hash
+table entries exact a small continuous performance penalty, since they
+must be scanned at every garbage collection. If the number of entries
+in the hash table is unknown, simply avoid using the `:size' keyword.
+
+ Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
+the algorithm for deciding when to rehash the hash table. For
+temporary hash tables that are going to be very heavily used, use a
+small rehash threshold, for example, 0.4 and a large rehash size, for
+example 2.0. For permanent hash tables that will be infrequently used,
+specify a large rehash threshold, for example 0.8.
+
+ Hash tables can also be created by the lisp reader using structure
+syntax, for example:
+ #s(hash-table size 20 data (foo 1 bar 2))
+
+ The structure syntax accepts the same keywords as `make-hash-table'
+(without the `:' character), as well as the additional keyword `data',
+which specifies the initial hash table contents.
+
+ - Function: make-hash-table &key `test' `size' `rehash-size'
+ `rehash-threshold' `weakness'
+ This function returns a new empty hash table object.
+
+ Keyword `:test' can be `eq', `eql' (default) or `equal'.
+ Comparison between keys is done using this function. If speed is
+ important, consider using `eq'. When storing strings in the hash
+ table, you will likely need to use `equal'.
+
+ Keyword `:size' specifies the number of keys likely to be inserted.
+ This number of entries can be inserted without enlarging the hash
+ table.
+
+ Keyword `:rehash-size' must be a float greater than 1.0, and
+ specifies the factor by which to increase the size of the hash
+ table when enlarging.
+
+ Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
+ and specifies the load factor of the hash table which triggers
+ enlarging.
+
+ Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
+
+ A weak hash table is one whose pointers do not count as GC
+ referents: for any key-value pair in the hash table, if the only
+ remaining pointer to either the key or the value is in a weak hash
+ table, then the pair will be removed from the hash table, and the
+ key and value collected. A non-weak hash table (or any other
+ pointer) would prevent the object from being collected.
+
+ A key-weak hash table is similar to a fully-weak hash table except
+ that a key-value pair will be removed only if the key remains
+ unmarked outside of weak hash tables. The pair will remain in the
+ hash table if the key is pointed to by something other than a weak
+ hash table, even if the value is not.
+
+ A value-weak hash table is similar to a fully-weak hash table
+ except that a key-value pair will be removed only if the value
+ remains unmarked outside of weak hash tables. The pair will
+ remain in the hash table if the value is pointed to by something
+ other than a weak hash table, even if the key is not.
+
+ - Function: copy-hash-table hash-table
+ This function returns a new hash table which contains the same
+ keys and values as HASH-TABLE. The keys and values will not
+ themselves be copied.
+
+ - Function: hash-table-count hash-table
+ This function returns the number of entries in HASH-TABLE.
+
+ - Function: hash-table-test hash-table
+ This function returns the test function of HASH-TABLE. This can
+ be one of `eq', `eql' or `equal'.
+
+ - Function: hash-table-size hash-table
+ This function returns the current number of slots in HASH-TABLE,
+ whether occupied or not.
+
+ - Function: hash-table-rehash-size hash-table
+ This function returns the current rehash size of HASH-TABLE. This
+ is a float greater than 1.0; the factor by which HASH-TABLE is
+ enlarged when the rehash threshold is exceeded.
+
+ - Function: hash-table-rehash-threshold hash-table
+ This function returns the current rehash threshold of HASH-TABLE.
+ This is a float between 0.0 and 1.0; the maximum "load factor" of
+ HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
+
+ - Function: hash-table-weakness hash-table
+ This function returns the weakness of HASH-TABLE. This can be one
+ of `nil', `t', `key' or `value'.
+
+\1f
+File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
+
+Working With Hash Tables
+========================
+
+ - Function: puthash key value hash-table
+ This function hashes KEY to VALUE in HASH-TABLE.
+
+ - Function: gethash key hash-table &optional default
+ This function finds the hash value for KEY in HASH-TABLE. If
+ there is no entry for KEY in HASH-TABLE, DEFAULT is returned
+ (which in turn defaults to `nil').
+
+ - Function: remhash key hash-table
+ This function removes the entry for KEY from HASH-TABLE. Does
+ nothing if there is no entry for KEY in HASH-TABLE.
+
+ - Function: clrhash hash-table
+ This function removes all entries from HASH-TABLE, leaving it
+ empty.
+
+ - Function: maphash function hash-table
+ This function maps FUNCTION over entries in HASH-TABLE, calling it
+ with two args, each key and value in the hash table.
+
+ FUNCTION may not modify HASH-TABLE, with the one exception that
+ FUNCTION may remhash or puthash the entry currently being
+ processed by FUNCTION.
+
+\1f
+File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
+
+Weak Hash Tables
+================
+
+ A "weak hash table" is a special variety of hash table whose
+elements do not count as GC referents. For any key-value pair in such a
+hash table, if either the key or value (or in some cases, if one
+particular one of the two) has no references to it outside of weak hash
+tables (and similar structures such as weak lists), the pair will be
+removed from the table, and the key and value collected. A non-weak
+hash table (or any other pointer) would prevent the objects from being
+collected.
+
+ Weak hash tables are useful for keeping track of information in a
+non-obtrusive way, for example to implement caching. If the cache
+contains objects such as buffers, markers, image instances, etc. that
+will eventually disappear and get garbage-collected, using a weak hash
+table ensures that these objects are collected normally rather than
+remaining around forever, long past their actual period of use.
+(Otherwise, you'd have to explicitly map over the hash table every so
+often and remove unnecessary elements.)
+
+ There are three types of weak hash tables:
+
+fully weak hash tables
+ In these hash tables, a pair disappears if either the key or the
+ value is unreferenced outside of the table.
+
+key-weak hash tables
+ In these hash tables, a pair disappears if the key is unreferenced
+ outside of the table, regardless of how the value is referenced.
+
+value-weak hash tables
+ In these hash tables, a pair disappears if the value is
+ unreferenced outside of the table, regardless of how the key is
+ referenced.
+
+ Also see *Note Weak Lists::.
+
+ Weak hash tables are created by specifying the `:weakness' keyword to
+`make-hash-table'.
+
+\1f
+File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
+
+Range Tables
+************
+
+ A range table is a table that efficiently associated values with
+ranges of integers.
+
+ Note that range tables have a read syntax, like this:
+
+ #s(range-table data ((-3 2) foo (5 20) bar))
+
+ This maps integers in the range (-3, 2) to `foo' and integers in the
+range (5, 20) to `bar'.
+
+ - Function: range-table-p object
+ Return non-`nil' if OBJECT is a range table.
+
+* Menu:
+
+* Introduction to Range Tables:: Range tables efficiently map ranges of
+ integers to values.
+* Working With Range Tables:: Range table functions.
+
+\1f
+File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
+
+Introduction to Range Tables
+============================
+
+ - Function: make-range-table
+ Make a new, empty range table.
+
+ - Function: copy-range-table old-table
+ Make a new range table which contains the same values for the same
+ ranges as the given table. The values will not themselves be
+ copied.
+
+\1f
+File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
+
+Working With Range Tables
+=========================
+
+ - Function: get-range-table pos table &optional default
+ This function finds value for position POS in TABLE. If there is
+ no corresponding value, return DEFAULT (defaults to `nil').
+
+ - Function: put-range-table start end val table
+ This function sets the value for range (START, END) to be VAL in
+ TABLE.
+
+ - Function: remove-range-table start end table
+ This function removes the value for range (START, END) in TABLE.
+
+ - Function: clear-range-table table
+ This function flushes TABLE.
+
+ - Function: map-range-table function table
+ This function maps FUNCTION over entries in TABLE, calling it with
+ three args, the beginning and end of the range and the
+ corresponding value.
+
+\1f
+File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
+
+Databases
+*********
+
+ - Function: databasep object
+ This function returns non-`nil' if OBJECT is a database.
+
+* Menu:
+
+* Connecting to a Database::
+* Working With a Database::
+* Other Database Functions::
+
+\1f
+File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
+
+Connecting to a Database
+========================
+
+ - Function: open-database file &optional type subtype access mode
+ This function opens database FILE, using database method TYPE and
+ SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
+ can be any combination of `r' `w' and `+', for read, write, and
+ creation flags.
+
+ TYPE can have the value `'dbm' or `'berkeley_db' to select the
+ type of database file to use. (Note: XEmacs may not support both
+ of these types.)
+
+ For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should by
+ `nil'.
+
+ For a TYPE of `'berkeley_db', the following subtypes are
+ available: `'hash', `'btree', and `'recno'. See the manpages for
+ the Berkeley DB functions to more information about these types.
+
+ - Function: close-database obj
+ This function closes database OBJ.
+
+ - Function: database-live-p obj
+ This function returns `t' iff OBJ is an active database, else
+ `nil'.
+
+\1f
File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
Working With a Database
* Accepting Output:: Explicitly permitting subprocess output.
Waiting for subprocess output.
-\1f
-File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
-
-Process Buffers
----------------
-
- A process can (and usually does) have an "associated buffer", which
-is an ordinary Emacs buffer that is used for two purposes: storing the
-output from the process, and deciding when to kill the process. You
-can also use the buffer to identify a process to operate on, since in
-normal practice only one process is associated with any given buffer.
-Many applications of processes also use the buffer for editing input to
-be sent to the process, but this is not built into XEmacs Lisp.
-
- Unless the process has a filter function (*note Filter Functions::),
-its output is inserted in the associated buffer. The position to insert
-the output is determined by the `process-mark', which is then updated
-to point to the end of the text just inserted. Usually, but not
-always, the `process-mark' is at the end of the buffer.
-
- - Function: process-buffer process
- This function returns the associated buffer of the process PROCESS.
-
- (process-buffer (get-process "shell"))
- => #<buffer *shell*>
-
- - Function: process-mark process
- This function returns the process marker for PROCESS, which is the
- marker that says where to insert output from the process.
-
- If PROCESS does not have a buffer, `process-mark' returns a marker
- that points nowhere.
-
- Insertion of process output in a buffer uses this marker to decide
- where to insert, and updates it to point after the inserted text.
- That is why successive batches of output are inserted
- consecutively.
-
- Filter functions normally should use this marker in the same
- fashion as is done by direct insertion of output in the buffer. A
- good example of a filter function that uses `process-mark' is
- found at the end of the following section.
-
- When the user is expected to enter input in the process buffer for
- transmission to the process, the process marker is useful for
- distinguishing the new input from previous output.
-
- - Function: set-process-buffer process buffer
- This function sets the buffer associated with PROCESS to BUFFER.
- If BUFFER is `nil', the process becomes associated with no buffer.
-
- - Function: get-buffer-process buffer-or-name
- This function returns the process associated with BUFFER-OR-NAME.
- If there are several processes associated with it, then one is
- chosen. (Presently, the one chosen is the one most recently
- created.) It is usually a bad idea to have more than one process
- associated with the same buffer.
-
- (get-buffer-process "*shell*")
- => #<process shell>
-
- Killing the process's buffer deletes the process, which kills the
- subprocess with a `SIGHUP' signal (*note Signals to Processes::).
-
-\1f
-File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
-
-Process Filter Functions
-------------------------
-
- A process "filter function" is a function that receives the standard
-output from the associated process. If a process has a filter, then
-_all_ output from that process is passed to the filter. The process
-buffer is used directly for output from the process only when there is
-no filter.
-
- A filter function must accept two arguments: the associated process
-and a string, which is the output. The function is then free to do
-whatever it chooses with the output.
-
- A filter function runs only while XEmacs is waiting (e.g., for
-terminal input, or for time to elapse, or for process output). This
-avoids the timing errors that could result from running filters at
-random places in the middle of other Lisp programs. You may explicitly
-cause Emacs to wait, so that filter functions will run, by calling
-`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
-(*note Accepting Output::). Emacs is also waiting when the command loop
-is reading input.
-
- Quitting is normally inhibited within a filter function--otherwise,
-the effect of typing `C-g' at command level or to quit a user command
-would be unpredictable. If you want to permit quitting inside a filter
-function, bind `inhibit-quit' to `nil'. *Note Quitting::.
-
- If an error happens during execution of a filter function, it is
-caught automatically, so that it doesn't stop the execution of whatever
-program was running when the filter function was started. However, if
-`debug-on-error' is non-`nil', the error-catching is turned off. This
-makes it possible to use the Lisp debugger to debug the filter
-function. *Note Debugger::.
-
- Many filter functions sometimes or always insert the text in the
-process's buffer, mimicking the actions of XEmacs when there is no
-filter. Such filter functions need to use `set-buffer' in order to be
-sure to insert in that buffer. To avoid setting the current buffer
-semipermanently, these filter functions must use `unwind-protect' to
-make sure to restore the previous current buffer. They should also
-update the process marker, and in some cases update the value of point.
-Here is how to do these things:
-
- (defun ordinary-insertion-filter (proc string)
- (let ((old-buffer (current-buffer)))
- (unwind-protect
- (let (moving)
- (set-buffer (process-buffer proc))
- (setq moving (= (point) (process-mark proc)))
- (save-excursion
- ;; Insert the text, moving the process-marker.
- (goto-char (process-mark proc))
- (insert string)
- (set-marker (process-mark proc) (point)))
- (if moving (goto-char (process-mark proc))))
- (set-buffer old-buffer))))
-
-The reason to use an explicit `unwind-protect' rather than letting
-`save-excursion' restore the current buffer is so as to preserve the
-change in point made by `goto-char'.
-
- To make the filter force the process buffer to be visible whenever
-new text arrives, insert the following line just before the
-`unwind-protect':
-
- (display-buffer (process-buffer proc))
-
- To force point to move to the end of the new output no matter where
-it was previously, eliminate the variable `moving' and call `goto-char'
-unconditionally.
-
- In earlier Emacs versions, every filter function that did regexp
-searching or matching had to explicitly save and restore the match data.
-Now Emacs does this automatically; filter functions never need to do it
-explicitly. *Note Match Data::.
-
- A filter function that writes the output into the buffer of the
-process should check whether the buffer is still alive. If it tries to
-insert into a dead buffer, it will get an error. If the buffer is dead,
-`(buffer-name (process-buffer PROCESS))' returns `nil'.
-
- The output to the function may come in chunks of any size. A program
-that produces the same output twice in a row may send it as one batch
-of 200 characters one time, and five batches of 40 characters the next.
-
- - Function: set-process-filter process filter
- This function gives PROCESS the filter function FILTER. If FILTER
- is `nil', then the process will have no filter. If FILTER is `t',
- then no output from the process will be accepted until the filter
- is changed. (Output received during this time is not discarded,
- but is queued, and will be processed as soon as the filter is
- changed.)
-
- - Function: process-filter process
- This function returns the filter function of PROCESS, or `nil' if
- it has none. `t' means that output processing has been stopped.
-
- Here is an example of use of a filter function:
-
- (defun keep-output (process output)
- (setq kept (cons output kept)))
- => keep-output
- (setq kept nil)
- => nil
- (set-process-filter (get-process "shell") 'keep-output)
- => keep-output
- (process-send-string "shell" "ls ~/other\n")
- => nil
- kept
- => ("lewis@slug[8] % "
- "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
- address.txt backup.psf kolstad.psf
- backup.bib~ david.mss resume-Dec-86.mss~
- backup.err david.psf resume-Dec.psf
- backup.mss dland syllabus.mss
- "
- "#backups.mss# backup.mss~ kolstad.mss
- ")
-
-\1f
-File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
-
-Accepting Output from Processes
--------------------------------
-
- Output from asynchronous subprocesses normally arrives only while
-XEmacs is waiting for some sort of external event, such as elapsed time
-or terminal input. Occasionally it is useful in a Lisp program to
-explicitly permit output to arrive at a specific point, or even to wait
-until output arrives from a process.
-
- - Function: accept-process-output &optional process seconds millisec
- This function allows XEmacs to read pending output from processes.
- The output is inserted in the associated buffers or given to
- their filter functions. If PROCESS is non-`nil' then this
- function does not return until some output has been received from
- PROCESS.
-
- The arguments SECONDS and MILLISEC let you specify timeout
- periods. The former specifies a period measured in seconds and the
- latter specifies one measured in milliseconds. The two time
- periods thus specified are added together, and
- `accept-process-output' returns after that much time whether or
- not there has been any subprocess output. Note that SECONDS is
- allowed to be a floating-point number; thus, there is no need to
- ever use MILLISEC. (It is retained for compatibility purposes.)
-
- The function `accept-process-output' returns non-`nil' if it did
- get some output, or `nil' if the timeout expired before output
- arrived.
-
-\1f
-File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
-
-Sentinels: Detecting Process Status Changes
-===========================================
-
- A "process sentinel" is a function that is called whenever the
-associated process changes status for any reason, including signals
-(whether sent by XEmacs or caused by the process's own actions) that
-terminate, stop, or continue the process. The process sentinel is also
-called if the process exits. The sentinel receives two arguments: the
-process for which the event occurred, and a string describing the type
-of event.
-
- The string describing the event looks like one of the following:
-
- * `"finished\n"'.
-
- * `"exited abnormally with code EXITCODE\n"'.
-
- * `"NAME-OF-SIGNAL\n"'.
-
- * `"NAME-OF-SIGNAL (core dumped)\n"'.
-
- A sentinel runs only while XEmacs is waiting (e.g., for terminal
-input, or for time to elapse, or for process output). This avoids the
-timing errors that could result from running them at random places in
-the middle of other Lisp programs. A program can wait, so that
-sentinels will run, by calling `sit-for' or `sleep-for' (*note
-Waiting::), or `accept-process-output' (*note Accepting Output::).
-Emacs is also waiting when the command loop is reading input.
-
- Quitting is normally inhibited within a sentinel--otherwise, the
-effect of typing `C-g' at command level or to quit a user command would
-be unpredictable. If you want to permit quitting inside a sentinel,
-bind `inhibit-quit' to `nil'. *Note Quitting::.
-
- A sentinel that writes the output into the buffer of the process
-should check whether the buffer is still alive. If it tries to insert
-into a dead buffer, it will get an error. If the buffer is dead,
-`(buffer-name (process-buffer PROCESS))' returns `nil'.
-
- If an error happens during execution of a sentinel, it is caught
-automatically, so that it doesn't stop the execution of whatever
-programs was running when the sentinel was started. However, if
-`debug-on-error' is non-`nil', the error-catching is turned off. This
-makes it possible to use the Lisp debugger to debug the sentinel.
-*Note Debugger::.
-
- In earlier Emacs versions, every sentinel that did regexp searching
-or matching had to explicitly save and restore the match data. Now
-Emacs does this automatically; sentinels never need to do it explicitly.
-*Note Match Data::.
-
- - Function: set-process-sentinel process sentinel
- This function associates SENTINEL with PROCESS. If SENTINEL is
- `nil', then the process will have no sentinel. The default
- behavior when there is no sentinel is to insert a message in the
- process's buffer when the process status changes.
-
- (defun msg-me (process event)
- (princ
- (format "Process: %s had the event `%s'" process event)))
- (set-process-sentinel (get-process "shell") 'msg-me)
- => msg-me
- (kill-process (get-process "shell"))
- -| Process: #<process shell> had the event `killed'
- => #<process shell>
-
- - Function: process-sentinel process
- This function returns the sentinel of PROCESS, or `nil' if it has
- none.
-
- - Function: waiting-for-user-input-p
- While a sentinel or filter function is running, this function
- returns non-`nil' if XEmacs was waiting for keyboard input from
- the user at the time the sentinel or filter function was called,
- `nil' if it was not.
-
-\1f
-File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
-
-Process Window Size
-===================
-
- - Function: set-process-window-size process height width
- This function tells PROCESS that its logical window size is HEIGHT
- by WIDTH characters. This is principally useful with pty's.
-
-\1f
-File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
-
-Transaction Queues
-==================
-
- You can use a "transaction queue" for more convenient communication
-with subprocesses using transactions. First use `tq-create' to create
-a transaction queue communicating with a specified process. Then you
-can call `tq-enqueue' to send a transaction.
-
- - Function: tq-create process
- This function creates and returns a transaction queue
- communicating with PROCESS. The argument PROCESS should be a
- subprocess capable of sending and receiving streams of bytes. It
- may be a child process, or it may be a TCP connection to a server,
- possibly on another machine.
-
- - Function: tq-enqueue queue question regexp closure fn
- This function sends a transaction to queue QUEUE. Specifying the
- queue has the effect of specifying the subprocess to talk to.
-
- The argument QUESTION is the outgoing message that starts the
- transaction. The argument FN is the function to call when the
- corresponding answer comes back; it is called with two arguments:
- CLOSURE, and the answer received.
-
- The argument REGEXP is a regular expression that should match the
- entire answer, but nothing less; that's how `tq-enqueue' determines
- where the answer ends.
-
- The return value of `tq-enqueue' itself is not meaningful.
-
- - Function: tq-close queue
- Shut down transaction queue QUEUE, waiting for all pending
- transactions to complete, and then terminate the connection or
- child process.
-
- Transaction queues are implemented by means of a filter function.
-*Note Filter Functions::.
-
-\1f
-File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
-
-Network Connections
-===================
-
- XEmacs Lisp programs can open TCP network connections to other
-processes on the same machine or other machines. A network connection
-is handled by Lisp much like a subprocess, and is represented by a
-process object. However, the process you are communicating with is not
-a child of the XEmacs process, so you can't kill it or send it signals.
-All you can do is send and receive data. `delete-process' closes the
-connection, but does not kill the process at the other end; that
-process must decide what to do about closure of the connection.
-
- You can distinguish process objects representing network connections
-from those representing subprocesses with the `process-status'
-function. It always returns either `open' or `closed' for a network
-connection, and it never returns either of those values for a real
-subprocess. *Note Process Information::.
-
- - Function: open-network-stream name buffer-or-name host service
- This function opens a TCP connection for a service to a host. It
- returns a process object to represent the connection.
-
- The NAME argument specifies the name for the process object. It
- is modified as necessary to make it unique.
-
- The BUFFER-OR-NAME argument is the buffer to associate with the
- connection. Output from the connection is inserted in the buffer,
- unless you specify a filter function to handle the output. If
- BUFFER-OR-NAME is `nil', it means that the connection is not
- associated with any buffer.
-
- The arguments HOST and SERVICE specify where to connect to; HOST
- is the host name or IP address (a string), and SERVICE is the name
- of a defined network service (a string) or a port number (an
- integer).
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
+
+Process Buffers
+---------------
+
+ A process can (and usually does) have an "associated buffer", which
+is an ordinary Emacs buffer that is used for two purposes: storing the
+output from the process, and deciding when to kill the process. You
+can also use the buffer to identify a process to operate on, since in
+normal practice only one process is associated with any given buffer.
+Many applications of processes also use the buffer for editing input to
+be sent to the process, but this is not built into XEmacs Lisp.
+
+ Unless the process has a filter function (*note Filter Functions::),
+its output is inserted in the associated buffer. The position to insert
+the output is determined by the `process-mark', which is then updated
+to point to the end of the text just inserted. Usually, but not
+always, the `process-mark' is at the end of the buffer.
+
+ - Function: process-buffer process
+ This function returns the associated buffer of the process PROCESS.
+
+ (process-buffer (get-process "shell"))
+ => #<buffer *shell*>
+
+ - Function: process-mark process
+ This function returns the process marker for PROCESS, which is the
+ marker that says where to insert output from the process.
+
+ If PROCESS does not have a buffer, `process-mark' returns a marker
+ that points nowhere.
+
+ Insertion of process output in a buffer uses this marker to decide
+ where to insert, and updates it to point after the inserted text.
+ That is why successive batches of output are inserted
+ consecutively.
+
+ Filter functions normally should use this marker in the same
+ fashion as is done by direct insertion of output in the buffer. A
+ good example of a filter function that uses `process-mark' is
+ found at the end of the following section.
+
+ When the user is expected to enter input in the process buffer for
+ transmission to the process, the process marker is useful for
+ distinguishing the new input from previous output.
+
+ - Function: set-process-buffer process buffer
+ This function sets the buffer associated with PROCESS to BUFFER.
+ If BUFFER is `nil', the process becomes associated with no buffer.
+
+ - Function: get-buffer-process buffer-or-name
+ This function returns the process associated with BUFFER-OR-NAME.
+ If there are several processes associated with it, then one is
+ chosen. (Presently, the one chosen is the one most recently
+ created.) It is usually a bad idea to have more than one process
+ associated with the same buffer.
+
+ (get-buffer-process "*shell*")
+ => #<process shell>
+
+ Killing the process's buffer deletes the process, which kills the
+ subprocess with a `SIGHUP' signal (*note Signals to Processes::).
+
+\1f
+File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
+
+Process Filter Functions
+------------------------
+
+ A process "filter function" is a function that receives the standard
+output from the associated process. If a process has a filter, then
+_all_ output from that process is passed to the filter. The process
+buffer is used directly for output from the process only when there is
+no filter.
+
+ A filter function must accept two arguments: the associated process
+and a string, which is the output. The function is then free to do
+whatever it chooses with the output.
+
+ A filter function runs only while XEmacs is waiting (e.g., for
+terminal input, or for time to elapse, or for process output). This
+avoids the timing errors that could result from running filters at
+random places in the middle of other Lisp programs. You may explicitly
+cause Emacs to wait, so that filter functions will run, by calling
+`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
+(*note Accepting Output::). Emacs is also waiting when the command loop
+is reading input.
+
+ Quitting is normally inhibited within a filter function--otherwise,
+the effect of typing `C-g' at command level or to quit a user command
+would be unpredictable. If you want to permit quitting inside a filter
+function, bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ If an error happens during execution of a filter function, it is
+caught automatically, so that it doesn't stop the execution of whatever
+program was running when the filter function was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the filter
+function. *Note Debugger::.
+
+ Many filter functions sometimes or always insert the text in the
+process's buffer, mimicking the actions of XEmacs when there is no
+filter. Such filter functions need to use `set-buffer' in order to be
+sure to insert in that buffer. To avoid setting the current buffer
+semipermanently, these filter functions must use `unwind-protect' to
+make sure to restore the previous current buffer. They should also
+update the process marker, and in some cases update the value of point.
+Here is how to do these things:
+
+ (defun ordinary-insertion-filter (proc string)
+ (let ((old-buffer (current-buffer)))
+ (unwind-protect
+ (let (moving)
+ (set-buffer (process-buffer proc))
+ (setq moving (= (point) (process-mark proc)))
+ (save-excursion
+ ;; Insert the text, moving the process-marker.
+ (goto-char (process-mark proc))
+ (insert string)
+ (set-marker (process-mark proc) (point)))
+ (if moving (goto-char (process-mark proc))))
+ (set-buffer old-buffer))))
+
+The reason to use an explicit `unwind-protect' rather than letting
+`save-excursion' restore the current buffer is so as to preserve the
+change in point made by `goto-char'.
+
+ To make the filter force the process buffer to be visible whenever
+new text arrives, insert the following line just before the
+`unwind-protect':
+
+ (display-buffer (process-buffer proc))
+
+ To force point to move to the end of the new output no matter where
+it was previously, eliminate the variable `moving' and call `goto-char'
+unconditionally.
+
+ In earlier Emacs versions, every filter function that did regexp
+searching or matching had to explicitly save and restore the match data.
+Now Emacs does this automatically; filter functions never need to do it
+explicitly. *Note Match Data::.
+
+ A filter function that writes the output into the buffer of the
+process should check whether the buffer is still alive. If it tries to
+insert into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ The output to the function may come in chunks of any size. A program
+that produces the same output twice in a row may send it as one batch
+of 200 characters one time, and five batches of 40 characters the next.
+
+ - Function: set-process-filter process filter
+ This function gives PROCESS the filter function FILTER. If FILTER
+ is `nil', then the process will have no filter. If FILTER is `t',
+ then no output from the process will be accepted until the filter
+ is changed. (Output received during this time is not discarded,
+ but is queued, and will be processed as soon as the filter is
+ changed.)
+
+ - Function: process-filter process
+ This function returns the filter function of PROCESS, or `nil' if
+ it has none. `t' means that output processing has been stopped.
+
+ Here is an example of use of a filter function:
+
+ (defun keep-output (process output)
+ (setq kept (cons output kept)))
+ => keep-output
+ (setq kept nil)
+ => nil
+ (set-process-filter (get-process "shell") 'keep-output)
+ => keep-output
+ (process-send-string "shell" "ls ~/other\n")
+ => nil
+ kept
+ => ("lewis@slug[8] % "
+ "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
+ address.txt backup.psf kolstad.psf
+ backup.bib~ david.mss resume-Dec-86.mss~
+ backup.err david.psf resume-Dec.psf
+ backup.mss dland syllabus.mss
+ "
+ "#backups.mss# backup.mss~ kolstad.mss
+ ")
+
+\1f
+File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
+
+Accepting Output from Processes
+-------------------------------
+
+ Output from asynchronous subprocesses normally arrives only while
+XEmacs is waiting for some sort of external event, such as elapsed time
+or terminal input. Occasionally it is useful in a Lisp program to
+explicitly permit output to arrive at a specific point, or even to wait
+until output arrives from a process.
+
+ - Function: accept-process-output &optional process seconds millisec
+ This function allows XEmacs to read pending output from processes.
+ The output is inserted in the associated buffers or given to
+ their filter functions. If PROCESS is non-`nil' then this
+ function does not return until some output has been received from
+ PROCESS.
+
+ The arguments SECONDS and MILLISEC let you specify timeout
+ periods. The former specifies a period measured in seconds and the
+ latter specifies one measured in milliseconds. The two time
+ periods thus specified are added together, and
+ `accept-process-output' returns after that much time whether or
+ not there has been any subprocess output. Note that SECONDS is
+ allowed to be a floating-point number; thus, there is no need to
+ ever use MILLISEC. (It is retained for compatibility purposes.)
+
+ The function `accept-process-output' returns non-`nil' if it did
+ get some output, or `nil' if the timeout expired before output
+ arrived.
+
+\1f
+File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
+
+Sentinels: Detecting Process Status Changes
+===========================================
+
+ A "process sentinel" is a function that is called whenever the
+associated process changes status for any reason, including signals
+(whether sent by XEmacs or caused by the process's own actions) that
+terminate, stop, or continue the process. The process sentinel is also
+called if the process exits. The sentinel receives two arguments: the
+process for which the event occurred, and a string describing the type
+of event.
+
+ The string describing the event looks like one of the following:
+
+ * `"finished\n"'.
+
+ * `"exited abnormally with code EXITCODE\n"'.
+
+ * `"NAME-OF-SIGNAL\n"'.
+
+ * `"NAME-OF-SIGNAL (core dumped)\n"'.
+
+ A sentinel runs only while XEmacs is waiting (e.g., for terminal
+input, or for time to elapse, or for process output). This avoids the
+timing errors that could result from running them at random places in
+the middle of other Lisp programs. A program can wait, so that
+sentinels will run, by calling `sit-for' or `sleep-for' (*note
+Waiting::), or `accept-process-output' (*note Accepting Output::).
+Emacs is also waiting when the command loop is reading input.
+
+ Quitting is normally inhibited within a sentinel--otherwise, the
+effect of typing `C-g' at command level or to quit a user command would
+be unpredictable. If you want to permit quitting inside a sentinel,
+bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ A sentinel that writes the output into the buffer of the process
+should check whether the buffer is still alive. If it tries to insert
+into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ If an error happens during execution of a sentinel, it is caught
+automatically, so that it doesn't stop the execution of whatever
+programs was running when the sentinel was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the sentinel.
+*Note Debugger::.
+
+ In earlier Emacs versions, every sentinel that did regexp searching
+or matching had to explicitly save and restore the match data. Now
+Emacs does this automatically; sentinels never need to do it explicitly.
+*Note Match Data::.
+
+ - Function: set-process-sentinel process sentinel
+ This function associates SENTINEL with PROCESS. If SENTINEL is
+ `nil', then the process will have no sentinel. The default
+ behavior when there is no sentinel is to insert a message in the
+ process's buffer when the process status changes.
+
+ (defun msg-me (process event)
+ (princ
+ (format "Process: %s had the event `%s'" process event)))
+ (set-process-sentinel (get-process "shell") 'msg-me)
+ => msg-me
+ (kill-process (get-process "shell"))
+ -| Process: #<process shell> had the event `killed'
+ => #<process shell>
+
+ - Function: process-sentinel process
+ This function returns the sentinel of PROCESS, or `nil' if it has
+ none.
+
+ - Function: waiting-for-user-input-p
+ While a sentinel or filter function is running, this function
+ returns non-`nil' if XEmacs was waiting for keyboard input from
+ the user at the time the sentinel or filter function was called,
+ `nil' if it was not.
+
+\1f
+File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
+
+Process Window Size
+===================
+
+ - Function: set-process-window-size process height width
+ This function tells PROCESS that its logical window size is HEIGHT
+ by WIDTH characters. This is principally useful with pty's.
+
+\1f
+File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
+
+Transaction Queues
+==================
+
+ You can use a "transaction queue" for more convenient communication
+with subprocesses using transactions. First use `tq-create' to create
+a transaction queue communicating with a specified process. Then you
+can call `tq-enqueue' to send a transaction.
+
+ - Function: tq-create process
+ This function creates and returns a transaction queue
+ communicating with PROCESS. The argument PROCESS should be a
+ subprocess capable of sending and receiving streams of bytes. It
+ may be a child process, or it may be a TCP connection to a server,
+ possibly on another machine.
+
+ - Function: tq-enqueue queue question regexp closure fn
+ This function sends a transaction to queue QUEUE. Specifying the
+ queue has the effect of specifying the subprocess to talk to.
+
+ The argument QUESTION is the outgoing message that starts the
+ transaction. The argument FN is the function to call when the
+ corresponding answer comes back; it is called with two arguments:
+ CLOSURE, and the answer received.
+
+ The argument REGEXP is a regular expression that should match the
+ entire answer, but nothing less; that's how `tq-enqueue' determines
+ where the answer ends.
+
+ The return value of `tq-enqueue' itself is not meaningful.
+
+ - Function: tq-close queue
+ Shut down transaction queue QUEUE, waiting for all pending
+ transactions to complete, and then terminate the connection or
+ child process.
+
+ Transaction queues are implemented by means of a filter function.
+*Note Filter Functions::.
+
+\1f
+File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
+
+Network Connections
+===================
+
+ XEmacs Lisp programs can open TCP network connections to other
+processes on the same machine or other machines. A network connection
+is handled by Lisp much like a subprocess, and is represented by a
+process object. However, the process you are communicating with is not
+a child of the XEmacs process, so you can't kill it or send it signals.
+All you can do is send and receive data. `delete-process' closes the
+connection, but does not kill the process at the other end; that
+process must decide what to do about closure of the connection.
+
+ You can distinguish process objects representing network connections
+from those representing subprocesses with the `process-status'
+function. It always returns either `open' or `closed' for a network
+connection, and it never returns either of those values for a real
+subprocess. *Note Process Information::.
+
+ - Function: open-network-stream name buffer-or-name host service
+ This function opens a TCP connection for a service to a host. It
+ returns a process object to represent the connection.
+
+ The NAME argument specifies the name for the process object. It
+ is modified as necessary to make it unique.
+
+ The BUFFER-OR-NAME argument is the buffer to associate with the
+ connection. Output from the connection is inserted in the buffer,
+ unless you specify a filter function to handle the output. If
+ BUFFER-OR-NAME is `nil', it means that the connection is not
+ associated with any buffer.
+
+ The arguments HOST and SERVICE specify where to connect to; HOST
+ is the host name or IP address (a string), and SERVICE is the name
+ of a defined network service (a string) or a port number (an
+ integer).
+
+\1f
File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
Operating System Interface
3. Return "C:\", as a fallback, but issue a warning.
-\1f
-File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
-
-Time of Day
-===========
-
- This section explains how to determine the current time and the time
-zone.
-
- - Function: current-time-string &optional time-value
- This function returns the current time and date as a
- humanly-readable string. The format of the string is unvarying;
- the number of characters used for each part is always the same, so
- you can reliably use `substring' to extract pieces of it. It is
- wise to count the characters from the beginning of the string
- rather than from the end, as additional information may be added
- at the end.
-
- The argument TIME-VALUE, if given, specifies a time to format
- instead of the current time. The argument should be a list whose
- first two elements are integers. Thus, you can use times obtained
- from `current-time' (see below) and from `file-attributes' (*note
- File Attributes::).
-
- (current-time-string)
- => "Wed Oct 14 22:21:05 1987"
-
- - Function: current-time
- This function returns the system's time value as a list of three
- integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
- combine to give the number of seconds since 0:00 January 1, 1970,
- which is HIGH * 2**16 + LOW.
-
- The third element, MICROSEC, gives the microseconds since the
- start of the current second (or 0 for systems that return time
- only on the resolution of a second).
-
- The first two elements can be compared with file time values such
- as you get with the function `file-attributes'. *Note File
- Attributes::.
-
- - Function: current-time-zone &optional time-value
- This function returns a list describing the time zone that the
- user is in.
-
- The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
- giving the number of seconds ahead of UTC (east of Greenwich). A
- negative value means west of Greenwich. The second element, NAME
- is a string giving the name of the time zone. Both elements
- change when daylight savings time begins or ends; if the user has
- specified a time zone that does not use a seasonal time
- adjustment, then the value is constant through time.
-
- If the operating system doesn't supply all the information
- necessary to compute the value, both elements of the list are
- `nil'.
-
- The argument TIME-VALUE, if given, specifies a time to analyze
- instead of the current time. The argument should be a cons cell
- containing two integers, or a list whose first two elements are
- integers. Thus, you can use times obtained from `current-time'
- (see above) and from `file-attributes' (*note File Attributes::).
-
-\1f
-File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
-
-Time Conversion
-===============
-
- These functions convert time values (lists of two or three integers)
-to strings or to calendrical information. There is also a function to
-convert calendrical information to a time value. You can get time
-values from the functions `current-time' (*note Time of Day::) and
-`file-attributes' (*note File Attributes::).
-
- - Function: format-time-string format-string &optional time
- This function converts TIME to a string according to
- FORMAT-STRING. If TIME is omitted, it defaults to the current
- time. The argument FORMAT-STRING may contain `%'-sequences which
- say to substitute parts of the time. Here is a table of what the
- `%'-sequences mean:
-
- `%a'
- This stands for the abbreviated name of the day of week.
-
- `%A'
- This stands for the full name of the day of week.
-
- `%b'
- This stands for the abbreviated name of the month.
-
- `%B'
- This stands for the full name of the month.
-
- `%c'
- This is a synonym for `%x %X'.
-
- `%C'
- This has a locale-specific meaning. In the default locale
- (named C), it is equivalent to `%A, %B %e, %Y'.
-
- `%d'
- This stands for the day of month, zero-padded.
-
- `%D'
- This is a synonym for `%m/%d/%y'.
-
- `%e'
- This stands for the day of month, blank-padded.
-
- `%h'
- This is a synonym for `%b'.
-
- `%H'
- This stands for the hour (00-23).
-
- `%I'
- This stands for the hour (00-12).
-
- `%j'
- This stands for the day of the year (001-366).
-
- `%k'
- This stands for the hour (0-23), blank padded.
-
- `%l'
- This stands for the hour (1-12), blank padded.
-
- `%m'
- This stands for the month (01-12).
-
- `%M'
- This stands for the minute (00-59).
-
- `%n'
- This stands for a newline.
-
- `%p'
- This stands for `AM' or `PM', as appropriate.
-
- `%r'
- This is a synonym for `%I:%M:%S %p'.
-
- `%R'
- This is a synonym for `%H:%M'.
-
- `%S'
- This stands for the seconds (00-60).
-
- `%t'
- This stands for a tab character.
-
- `%T'
- This is a synonym for `%H:%M:%S'.
-
- `%U'
- This stands for the week of the year (01-52), assuming that
- weeks start on Sunday.
-
- `%w'
- This stands for the numeric day of week (0-6). Sunday is day
- 0.
-
- `%W'
- This stands for the week of the year (01-52), assuming that
- weeks start on Monday.
-
- `%x'
- This has a locale-specific meaning. In the default locale
- (named C), it is equivalent to `%D'.
-
- `%X'
- This has a locale-specific meaning. In the default locale
- (named C), it is equivalent to `%T'.
-
- `%y'
- This stands for the year without century (00-99).
-
- `%Y'
- This stands for the year with century.
-
- `%Z'
- This stands for the time zone abbreviation.
-
- - Function: decode-time time
- This function converts a time value into calendrical information.
- The return value is a list of nine elements, as follows:
-
- (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
-
- Here is what the elements mean:
-
- SEC
- The number of seconds past the minute, as an integer between
- 0 and 59.
-
- MINUTE
- The number of minutes past the hour, as an integer between 0
- and 59.
-
- HOUR
- The hour of the day, as an integer between 0 and 23.
-
- DAY
- The day of the month, as an integer between 1 and 31.
-
- MONTH
- The month of the year, as an integer between 1 and 12.
-
- YEAR
- The year, an integer typically greater than 1900.
-
- DOW
- The day of week, as an integer between 0 and 6, where 0
- stands for Sunday.
-
- DST
- `t' if daylight savings time is effect, otherwise `nil'.
-
- ZONE
- An integer indicating the time zone, as the number of seconds
- east of Greenwich.
-
- Note that Common Lisp has different meanings for DOW and ZONE.
-
- - Function: encode-time seconds minutes hour day month year &optional
- zone
- This function is the inverse of `decode-time'. It converts seven
- items of calendrical data into a time value. For the meanings of
- the arguments, see the table above under `decode-time'.
-
- Year numbers less than 100 are treated just like other year
- numbers. If you want them to stand for years above 1900, you must
- alter them yourself before you call `encode-time'.
-
- The optional argument ZONE defaults to the current time zone and
- its daylight savings time rules. If specified, it can be either a
- list (as you would get from `current-time-zone') or an integer (as
- you would get from `decode-time'). The specified zone is used
- without any further alteration for daylight savings time.
-
-\1f
-File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
-
-Timers for Delayed Execution
-============================
-
- You can set up a timer to call a function at a specified future time.
-
- - Function: add-timeout secs function object &optional resignal
- This function adds a timeout, to be signaled after the timeout
- period has elapsed. SECS is a number of seconds, expressed as an
- integer or a float. FUNCTION will be called after that many
- seconds have elapsed, with one argument, the given OBJECT. If the
- optional RESIGNAL argument is provided, then after this timeout
- expires, `add-timeout' will automatically be called again with
- RESIGNAL as the first argument.
-
- This function returns an object which is the "id" of this
- particular timeout. You can pass that object to `disable-timeout'
- to turn off the timeout before it has been signalled.
-
- The number of seconds may be expressed as a floating-point number,
- in which case some fractional part of a second will be used.
- Caveat: the usable timeout granularity will vary from system to
- system.
-
- Adding a timeout causes a timeout event to be returned by
- `next-event', and the function will be invoked by
- `dispatch-event', so if XEmacs is in a tight loop, the function
- will not be invoked until the next call to sit-for or until the
- return to top-level (the same is true of process filters).
-
- WARNING: if you are thinking of calling add-timeout from inside of
- a callback function as a way of resignalling a timeout, think
- again. There is a race condition. That's why the RESIGNAL
- argument exists.
-
- (NOTE: In FSF Emacs, this function is called `run-at-time' and has
- different semantics.)
-
- - Function: disable-timeout id
- Cancel the requested action for ID, which should be a value
- previously returned by `add-timeout'. This cancels the effect of
- that call to `add-timeout'; the arrival of the specified time will
- not cause anything special to happen. (NOTE: In FSF Emacs, this
- function is called `cancel-timer'.)
-
-\1f
-File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
-
-Terminal Input
-==============
-
- This section describes functions and variables for recording or
-manipulating terminal input. See *Note Display::, for related
-functions.
-
-* Menu:
-
-* Input Modes:: Options for how input is processed.
-* Translating Input:: Low level conversion of some characters or events
- into others.
-* Recording Input:: Saving histories of recent or all input events.
-
-\1f
-File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
-
-Input Modes
------------
-
- - Function: set-input-mode interrupt flow meta quit-char
- This function sets the mode for reading keyboard input. If
- INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
- `nil', then it uses CBREAK mode. When XEmacs communicates
- directly with X, it ignores this argument and uses interrupts if
- that is the way it knows how to communicate.
-
- If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
- flow control for output to the terminal. This has no effect except
- in CBREAK mode. *Note Flow Control::.
-
- The default setting is system dependent. Some systems always use
- CBREAK mode regardless of what is specified.
-
- The argument META controls support for input character codes above
- 127. If META is `t', XEmacs converts characters with the 8th bit
- set into Meta characters. If META is `nil', XEmacs disregards the
- 8th bit; this is necessary when the terminal uses it as a parity
- bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
- input unchanged. This is good for terminals using European 8-bit
- character sets.
-
- If QUIT-CHAR is non-`nil', it specifies the character to use for
- quitting. Normally this character is `C-g'. *Note Quitting::.
-
- The `current-input-mode' function returns the input mode settings
-XEmacs is currently using.
-
- - Function: current-input-mode
- This function returns current mode for reading keyboard input. It
- returns a list, corresponding to the arguments of `set-input-mode',
- of the form `(INTERRUPT FLOW META QUIT)' in which:
- INTERRUPT
- is non-`nil' when XEmacs is using interrupt-driven input. If
- `nil', Emacs is using CBREAK mode.
-
- FLOW
- is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
- control for output to the terminal. This value has no effect
- unless INTERRUPT is non-`nil'.
-
- META
- is `t' if XEmacs treats the eighth bit of input characters as
- the meta bit; `nil' means XEmacs clears the eighth bit of
- every input character; any other value means XEmacs uses all
- eight bits as the basic character code.
-
- QUIT
- is the character XEmacs currently uses for quitting, usually
- `C-g'.
-
-\1f
-File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
-
-Translating Input Events
-------------------------
-
- This section describes features for translating input events into
-other input events before they become part of key sequences.
-
- - Variable: function-key-map
- This variable holds a keymap that describes the character sequences
- sent by function keys on an ordinary character terminal. This
- keymap uses the same data structure as other keymaps, but is used
- differently: it specifies translations to make while reading
- events.
-
- If `function-key-map' "binds" a key sequence K to a vector V, then
- when K appears as a subsequence _anywhere_ in a key sequence, it
- is replaced with the events in V.
-
- For example, VT100 terminals send `<ESC> O P' when the keypad PF1
- key is pressed. Therefore, we want XEmacs to translate that
- sequence of events into the single event `pf1'. We accomplish
- this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
- when using a VT100.
-
- Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
- P'; later the function `read-key-sequence' translates this back
- into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
-
- Entries in `function-key-map' are ignored if they conflict with
- bindings made in the minor mode, local, or global keymaps. The
- intent is that the character sequences that function keys send
- should not have command bindings in their own right.
-
- The value of `function-key-map' is usually set up automatically
- according to the terminal's Terminfo or Termcap entry, but
- sometimes those need help from terminal-specific Lisp files.
- XEmacs comes with terminal-specific files for many common
- terminals; their main purpose is to make entries in
- `function-key-map' beyond those that can be deduced from Termcap
- and Terminfo. *Note Terminal-Specific::.
-
- Emacs versions 18 and earlier used totally different means of
- detecting the character sequences that represent function keys.
-
- - Variable: key-translation-map
- This variable is another keymap used just like `function-key-map'
- to translate input events into other events. It differs from
- `function-key-map' in two ways:
-
- * `key-translation-map' goes to work after `function-key-map' is
- finished; it receives the results of translation by
- `function-key-map'.
-
- * `key-translation-map' overrides actual key bindings.
-
- The intent of `key-translation-map' is for users to map one
- character set to another, including ordinary characters normally
- bound to `self-insert-command'.
-
- You can use `function-key-map' or `key-translation-map' for more
-than simple aliases, by using a function, instead of a key sequence, as
-the "translation" of a key. Then this function is called to compute
-the translation of that key.
-
- The key translation function receives one argument, which is the
-prompt that was specified in `read-key-sequence'--or `nil' if the key
-sequence is being read by the editor command loop. In most cases you
-can ignore the prompt value.
-
- If the function reads input itself, it can have the effect of
-altering the event that follows. For example, here's how to define
-`C-c h' to turn the character that follows into a Hyper character:
-
- (defun hyperify (prompt)
- (let ((e (read-event)))
- (vector (if (numberp e)
- (logior (lsh 1 20) e)
- (if (memq 'hyper (event-modifiers e))
- e
- (add-event-modifier "H-" e))))))
-
- (defun add-event-modifier (string e)
- (let ((symbol (if (symbolp e) e (car e))))
- (setq symbol (intern (concat string
- (symbol-name symbol))))
- (if (symbolp e)
- symbol
- (cons symbol (cdr e)))))
-
- (define-key function-key-map "\C-ch" 'hyperify)
-
- The `iso-transl' library uses this feature to provide a way of
-inputting non-ASCII Latin-1 characters.
-
-\1f
-File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
-
-Recording Input
----------------
-
- - Function: recent-keys &optional number
- This function returns a vector containing recent input events from
- the keyboard or mouse. By default, 100 events are recorded, which
- is how many `recent-keys' returns.
-
- All input events are included, whether or not they were used as
- parts of key sequences. Thus, you always get the last 100 inputs,
- not counting keyboard macros. (Events from keyboard macros are
- excluded because they are less interesting for debugging; it
- should be enough to see the events that invoked the macros.)
-
- If NUMBER is specified, not more than NUMBER events will be
- returned. You may change the number of stored events using
- `set-recent-keys-ring-size'.
-
- - Function: recent-keys-ring-size
- This function returns the number of recent events stored
- internally. This is also the maximum number of events
- `recent-keys' can return. By default, 100 events are stored.
-
- - Function: set-recent-keys-ring-size size
- This function changes the number of events stored by XEmacs and
- returned by `recent-keys'.
-
- For example, `(set-recent-keys-ring-size 250)' will make XEmacs
- remember last 250 events and will make `recent-keys' return last
- 250 events by default.
-
- - Command: open-dribble-file filename
- This function opens a "dribble file" named FILENAME. When a
- dribble file is open, each input event from the keyboard or mouse
- (but not those from keyboard macros) is written in that file. A
- non-character event is expressed using its printed representation
- surrounded by `<...>'.
-
- You close the dribble file by calling this function with an
- argument of `nil'.
-
- This function is normally used to record the input necessary to
- trigger an XEmacs bug, for the sake of a bug report.
-
- (open-dribble-file "~/dribble")
- => nil
-
- See also the `open-termscript' function (*note Terminal Output::).
-
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
+
+Time of Day
+===========
+
+ This section explains how to determine the current time and the time
+zone.
+
+ - Function: current-time-string &optional time-value
+ This function returns the current time and date as a
+ humanly-readable string. The format of the string is unvarying;
+ the number of characters used for each part is always the same, so
+ you can reliably use `substring' to extract pieces of it. It is
+ wise to count the characters from the beginning of the string
+ rather than from the end, as additional information may be added
+ at the end.
+
+ The argument TIME-VALUE, if given, specifies a time to format
+ instead of the current time. The argument should be a list whose
+ first two elements are integers. Thus, you can use times obtained
+ from `current-time' (see below) and from `file-attributes' (*note
+ File Attributes::).
+
+ (current-time-string)
+ => "Wed Oct 14 22:21:05 1987"
+
+ - Function: current-time
+ This function returns the system's time value as a list of three
+ integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
+ combine to give the number of seconds since 0:00 January 1, 1970,
+ which is HIGH * 2**16 + LOW.
+
+ The third element, MICROSEC, gives the microseconds since the
+ start of the current second (or 0 for systems that return time
+ only on the resolution of a second).
+
+ The first two elements can be compared with file time values such
+ as you get with the function `file-attributes'. *Note File
+ Attributes::.
+
+ - Function: current-time-zone &optional time-value
+ This function returns a list describing the time zone that the
+ user is in.
+
+ The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
+ giving the number of seconds ahead of UTC (east of Greenwich). A
+ negative value means west of Greenwich. The second element, NAME
+ is a string giving the name of the time zone. Both elements
+ change when daylight savings time begins or ends; if the user has
+ specified a time zone that does not use a seasonal time
+ adjustment, then the value is constant through time.
+
+ If the operating system doesn't supply all the information
+ necessary to compute the value, both elements of the list are
+ `nil'.
+
+ The argument TIME-VALUE, if given, specifies a time to analyze
+ instead of the current time. The argument should be a cons cell
+ containing two integers, or a list whose first two elements are
+ integers. Thus, you can use times obtained from `current-time'
+ (see above) and from `file-attributes' (*note File Attributes::).
+
+\1f
+File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
+
+Time Conversion
+===============
+
+ These functions convert time values (lists of two or three integers)
+to strings or to calendrical information. There is also a function to
+convert calendrical information to a time value. You can get time
+values from the functions `current-time' (*note Time of Day::) and
+`file-attributes' (*note File Attributes::).
+
+ - Function: format-time-string format-string &optional time
+ This function converts TIME to a string according to
+ FORMAT-STRING. If TIME is omitted, it defaults to the current
+ time. The argument FORMAT-STRING may contain `%'-sequences which
+ say to substitute parts of the time. Here is a table of what the
+ `%'-sequences mean:
+
+ `%a'
+ This stands for the abbreviated name of the day of week.
+
+ `%A'
+ This stands for the full name of the day of week.
+
+ `%b'
+ This stands for the abbreviated name of the month.
+
+ `%B'
+ This stands for the full name of the month.
+
+ `%c'
+ This is a synonym for `%x %X'.
+
+ `%C'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%A, %B %e, %Y'.
+
+ `%d'
+ This stands for the day of month, zero-padded.
+
+ `%D'
+ This is a synonym for `%m/%d/%y'.
+
+ `%e'
+ This stands for the day of month, blank-padded.
+
+ `%h'
+ This is a synonym for `%b'.
+
+ `%H'
+ This stands for the hour (00-23).
+
+ `%I'
+ This stands for the hour (00-12).
+
+ `%j'
+ This stands for the day of the year (001-366).
+
+ `%k'
+ This stands for the hour (0-23), blank padded.
+
+ `%l'
+ This stands for the hour (1-12), blank padded.
+
+ `%m'
+ This stands for the month (01-12).
+
+ `%M'
+ This stands for the minute (00-59).
+
+ `%n'
+ This stands for a newline.
+
+ `%p'
+ This stands for `AM' or `PM', as appropriate.
+
+ `%r'
+ This is a synonym for `%I:%M:%S %p'.
+
+ `%R'
+ This is a synonym for `%H:%M'.
+
+ `%S'
+ This stands for the seconds (00-60).
+
+ `%t'
+ This stands for a tab character.
+
+ `%T'
+ This is a synonym for `%H:%M:%S'.
+
+ `%U'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Sunday.
+
+ `%w'
+ This stands for the numeric day of week (0-6). Sunday is day
+ 0.
+
+ `%W'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Monday.
+
+ `%x'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%D'.
+
+ `%X'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%T'.
+
+ `%y'
+ This stands for the year without century (00-99).
+
+ `%Y'
+ This stands for the year with century.
+
+ `%Z'
+ This stands for the time zone abbreviation.
+
+ - Function: decode-time time
+ This function converts a time value into calendrical information.
+ The return value is a list of nine elements, as follows:
+
+ (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
+
+ Here is what the elements mean:
+
+ SEC
+ The number of seconds past the minute, as an integer between
+ 0 and 59.
+
+ MINUTE
+ The number of minutes past the hour, as an integer between 0
+ and 59.
+
+ HOUR
+ The hour of the day, as an integer between 0 and 23.
+
+ DAY
+ The day of the month, as an integer between 1 and 31.
+
+ MONTH
+ The month of the year, as an integer between 1 and 12.
+
+ YEAR
+ The year, an integer typically greater than 1900.
+
+ DOW
+ The day of week, as an integer between 0 and 6, where 0
+ stands for Sunday.
+
+ DST
+ `t' if daylight savings time is effect, otherwise `nil'.
+
+ ZONE
+ An integer indicating the time zone, as the number of seconds
+ east of Greenwich.
+
+ Note that Common Lisp has different meanings for DOW and ZONE.
+
+ - Function: encode-time seconds minutes hour day month year &optional
+ zone
+ This function is the inverse of `decode-time'. It converts seven
+ items of calendrical data into a time value. For the meanings of
+ the arguments, see the table above under `decode-time'.
+
+ Year numbers less than 100 are treated just like other year
+ numbers. If you want them to stand for years above 1900, you must
+ alter them yourself before you call `encode-time'.
+
+ The optional argument ZONE defaults to the current time zone and
+ its daylight savings time rules. If specified, it can be either a
+ list (as you would get from `current-time-zone') or an integer (as
+ you would get from `decode-time'). The specified zone is used
+ without any further alteration for daylight savings time.
+
+\1f
+File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
+
+Timers for Delayed Execution
+============================
+
+ You can set up a timer to call a function at a specified future time.
+
+ - Function: add-timeout secs function object &optional resignal
+ This function adds a timeout, to be signaled after the timeout
+ period has elapsed. SECS is a number of seconds, expressed as an
+ integer or a float. FUNCTION will be called after that many
+ seconds have elapsed, with one argument, the given OBJECT. If the
+ optional RESIGNAL argument is provided, then after this timeout
+ expires, `add-timeout' will automatically be called again with
+ RESIGNAL as the first argument.
+
+ This function returns an object which is the "id" of this
+ particular timeout. You can pass that object to `disable-timeout'
+ to turn off the timeout before it has been signalled.
+
+ The number of seconds may be expressed as a floating-point number,
+ in which case some fractional part of a second will be used.
+ Caveat: the usable timeout granularity will vary from system to
+ system.
+
+ Adding a timeout causes a timeout event to be returned by
+ `next-event', and the function will be invoked by
+ `dispatch-event', so if XEmacs is in a tight loop, the function
+ will not be invoked until the next call to sit-for or until the
+ return to top-level (the same is true of process filters).
+
+ WARNING: if you are thinking of calling add-timeout from inside of
+ a callback function as a way of resignalling a timeout, think
+ again. There is a race condition. That's why the RESIGNAL
+ argument exists.
+
+ (NOTE: In FSF Emacs, this function is called `run-at-time' and has
+ different semantics.)
+
+ - Function: disable-timeout id
+ Cancel the requested action for ID, which should be a value
+ previously returned by `add-timeout'. This cancels the effect of
+ that call to `add-timeout'; the arrival of the specified time will
+ not cause anything special to happen. (NOTE: In FSF Emacs, this
+ function is called `cancel-timer'.)
+
+\1f
+File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
+
+Terminal Input
+==============
+
+ This section describes functions and variables for recording or
+manipulating terminal input. See *Note Display::, for related
+functions.
+
+* Menu:
+
+* Input Modes:: Options for how input is processed.
+* Translating Input:: Low level conversion of some characters or events
+ into others.
+* Recording Input:: Saving histories of recent or all input events.
+
+\1f
+File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
+
+Input Modes
+-----------
+
+ - Function: set-input-mode interrupt flow meta quit-char
+ This function sets the mode for reading keyboard input. If
+ INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
+ `nil', then it uses CBREAK mode. When XEmacs communicates
+ directly with X, it ignores this argument and uses interrupts if
+ that is the way it knows how to communicate.
+
+ If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
+ flow control for output to the terminal. This has no effect except
+ in CBREAK mode. *Note Flow Control::.
+
+ The default setting is system dependent. Some systems always use
+ CBREAK mode regardless of what is specified.
+
+ The argument META controls support for input character codes above
+ 127. If META is `t', XEmacs converts characters with the 8th bit
+ set into Meta characters. If META is `nil', XEmacs disregards the
+ 8th bit; this is necessary when the terminal uses it as a parity
+ bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
+ input unchanged. This is good for terminals using European 8-bit
+ character sets.
+
+ If QUIT-CHAR is non-`nil', it specifies the character to use for
+ quitting. Normally this character is `C-g'. *Note Quitting::.
+
+ The `current-input-mode' function returns the input mode settings
+XEmacs is currently using.
+
+ - Function: current-input-mode
+ This function returns current mode for reading keyboard input. It
+ returns a list, corresponding to the arguments of `set-input-mode',
+ of the form `(INTERRUPT FLOW META QUIT)' in which:
+ INTERRUPT
+ is non-`nil' when XEmacs is using interrupt-driven input. If
+ `nil', Emacs is using CBREAK mode.
+
+ FLOW
+ is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
+ control for output to the terminal. This value has no effect
+ unless INTERRUPT is non-`nil'.
+
+ META
+ is `t' if XEmacs treats the eighth bit of input characters as
+ the meta bit; `nil' means XEmacs clears the eighth bit of
+ every input character; any other value means XEmacs uses all
+ eight bits as the basic character code.
+
+ QUIT
+ is the character XEmacs currently uses for quitting, usually
+ `C-g'.
+
+\1f
+File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
+
+Translating Input Events
+------------------------
+
+ This section describes features for translating input events into
+other input events before they become part of key sequences.
+
+ - Variable: function-key-map
+ This variable holds a keymap that describes the character sequences
+ sent by function keys on an ordinary character terminal. This
+ keymap uses the same data structure as other keymaps, but is used
+ differently: it specifies translations to make while reading
+ events.
+
+ If `function-key-map' "binds" a key sequence K to a vector V, then
+ when K appears as a subsequence _anywhere_ in a key sequence, it
+ is replaced with the events in V.
+
+ For example, VT100 terminals send `<ESC> O P' when the keypad PF1
+ key is pressed. Therefore, we want XEmacs to translate that
+ sequence of events into the single event `pf1'. We accomplish
+ this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
+ when using a VT100.
+
+ Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
+ P'; later the function `read-key-sequence' translates this back
+ into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
+
+ Entries in `function-key-map' are ignored if they conflict with
+ bindings made in the minor mode, local, or global keymaps. The
+ intent is that the character sequences that function keys send
+ should not have command bindings in their own right.
+
+ The value of `function-key-map' is usually set up automatically
+ according to the terminal's Terminfo or Termcap entry, but
+ sometimes those need help from terminal-specific Lisp files.
+ XEmacs comes with terminal-specific files for many common
+ terminals; their main purpose is to make entries in
+ `function-key-map' beyond those that can be deduced from Termcap
+ and Terminfo. *Note Terminal-Specific::.
+
+ Emacs versions 18 and earlier used totally different means of
+ detecting the character sequences that represent function keys.
+
+ - Variable: key-translation-map
+ This variable is another keymap used just like `function-key-map'
+ to translate input events into other events. It differs from
+ `function-key-map' in two ways:
+
+ * `key-translation-map' goes to work after `function-key-map' is
+ finished; it receives the results of translation by
+ `function-key-map'.
+
+ * `key-translation-map' overrides actual key bindings.
+
+ The intent of `key-translation-map' is for users to map one
+ character set to another, including ordinary characters normally
+ bound to `self-insert-command'.
+
+ You can use `function-key-map' or `key-translation-map' for more
+than simple aliases, by using a function, instead of a key sequence, as
+the "translation" of a key. Then this function is called to compute
+the translation of that key.
+
+ The key translation function receives one argument, which is the
+prompt that was specified in `read-key-sequence'--or `nil' if the key
+sequence is being read by the editor command loop. In most cases you
+can ignore the prompt value.
+
+ If the function reads input itself, it can have the effect of
+altering the event that follows. For example, here's how to define
+`C-c h' to turn the character that follows into a Hyper character:
+
+ (defun hyperify (prompt)
+ (let ((e (read-event)))
+ (vector (if (numberp e)
+ (logior (lsh 1 20) e)
+ (if (memq 'hyper (event-modifiers e))
+ e
+ (add-event-modifier "H-" e))))))
+
+ (defun add-event-modifier (string e)
+ (let ((symbol (if (symbolp e) e (car e))))
+ (setq symbol (intern (concat string
+ (symbol-name symbol))))
+ (if (symbolp e)
+ symbol
+ (cons symbol (cdr e)))))
+
+ (define-key function-key-map "\C-ch" 'hyperify)
+
+ The `iso-transl' library uses this feature to provide a way of
+inputting non-ASCII Latin-1 characters.
+
+\1f
+File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
+
+Recording Input
+---------------
+
+ - Function: recent-keys &optional number
+ This function returns a vector containing recent input events from
+ the keyboard or mouse. By default, 100 events are recorded, which
+ is how many `recent-keys' returns.
+
+ All input events are included, whether or not they were used as
+ parts of key sequences. Thus, you always get the last 100 inputs,
+ not counting keyboard macros. (Events from keyboard macros are
+ excluded because they are less interesting for debugging; it
+ should be enough to see the events that invoked the macros.)
+
+ If NUMBER is specified, not more than NUMBER events will be
+ returned. You may change the number of stored events using
+ `set-recent-keys-ring-size'.
+
+ - Function: recent-keys-ring-size
+ This function returns the number of recent events stored
+ internally. This is also the maximum number of events
+ `recent-keys' can return. By default, 100 events are stored.
+
+ - Function: set-recent-keys-ring-size size
+ This function changes the number of events stored by XEmacs and
+ returned by `recent-keys'.
+
+ For example, `(set-recent-keys-ring-size 250)' will make XEmacs
+ remember last 250 events and will make `recent-keys' return last
+ 250 events by default.
+
+ - Command: open-dribble-file filename
+ This function opens a "dribble file" named FILENAME. When a
+ dribble file is open, each input event from the keyboard or mouse
+ (but not those from keyboard macros) is written in that file. A
+ non-character event is expressed using its printed representation
+ surrounded by `<...>'.
+
+ You close the dribble file by calling this function with an
+ argument of `nil'.
+
+ This function is normally used to record the input necessary to
+ trigger an XEmacs bug, for the sake of a bug report.
+
+ (open-dribble-file "~/dribble")
+ => nil
+
+ See also the `open-termscript' function (*note Terminal Output::).
+
+\1f
File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
Terminal Output
(let ((m (make-tooltalk-message random-query-message)))
(send-tooltalk-message m))
-\1f
-File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
-
-Elisp Interface for Sending Messages
-------------------------------------
-
- - Function: make-tooltalk-message attributes
- Create a ToolTalk message and initialize its attributes. The
- value of ATTRIBUTES must be a list of alternating keyword/values,
- where keywords are symbols that name valid message attributes.
- For example:
-
- (make-tooltalk-message
- '(class TT_NOTICE
- scope TT_SESSION
- address TT_PROCEDURE
- op "do-something"
- args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
-
- Values must always be strings, integers, or symbols that represent
- ToolTalk constants. Attribute names are the same as those
- supported by `set-tooltalk-message-attribute', plus `args'.
-
- The value of `args' should be a list of message arguments where
- each message argument has the following form:
-
- `(mode [value [type]])' or just `value'
-
- Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
- a string. If TYPE isn't specified then `int' is used if VALUE is
- a number; otherwise `string' is used. If TYPE is `string' then
- VALUE is converted to a string (if it isn't a string already) with
- `prin1-to-string'. If only a value is specified then MODE
- defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
- don't need to be specified. You can find out more about the
- semantics and uses of ToolTalk message arguments in chapter 4 of
- the `ToolTalk Programmer's Guide'.
-
-
- - Function: send-tooltalk-message msg
- Send the message on its way. Once the message has been sent it's
- almost always a good idea to get rid of it with
- `destroy-tooltalk-message'.
-
-
- - Function: return-tooltalk-message msg &optional mode
- Send a reply to this message. The second argument can be `reply',
- `reject' or `fail'; the default is `reply'. Before sending a
- reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
- should have been filled in--see `set-tooltalk-message-attribute'.
-
-
- - Function: get-tooltalk-message-attribute msg attribute &optional argn
- Returns the indicated ToolTalk message attribute. Attributes are
- identified by symbols with the same name (underscores and all) as
- the suffix of the ToolTalk `tt_message_<attribute>' function that
- extracts the value. String attribute values are copied and
- enumerated type values (except disposition) are converted to
- symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
- represented by fixnums (small integers), `opnum' is converted to a
- string, and `disposition' is converted to a fixnum. We convert
- `opnum' (a C int) to a string (e.g. `123' => `"123"') because
- there's no guarantee that opnums will fit within the range of
- XEmacs Lisp integers.
-
- [TBD] Use the `plist' attribute instead of C API `user' attribute
- for user-defined message data. To retrieve the value of a message
- property, specify the indicator for ARGN. For example, to get the
- value of a property called `rflag', use
-
- (get-tooltalk-message-attribute msg 'plist 'rflag)
-
- To get the value of a message argument use one of the `arg_val'
- (strings), `arg_ival' (integers), or `arg_bval' (strings with
- embedded nulls), attributes. For example, to get the integer
- value of the third argument:
-
- (get-tooltalk-message-attribute msg 'arg_ival 2)
-
- As you can see, argument numbers are zero-based. The type of each
- arguments can be retrieved with the `arg_type' attribute; however
- ToolTalk doesn't define any semantics for the string value of
- `arg_type'. Conventionally `string' is used for strings and `int'
- for 32 bit integers. Note that XEmacs Lisp stores the lengths of
- strings explicitly (unlike C) so treating the value returned by
- `arg_bval' like a string is fine.
-
-
- - Function: set-tooltalk-message-attribute value msg attribute
- &optional argn
- Initialize one ToolTalk message attribute.
-
- Attribute names and values are the same as for
- `get-tooltalk-message-attribute'. A property list is provided for
- user data (instead of the `user' message attribute); see
- `get-tooltalk-message-attribute'.
-
- Callbacks are handled slightly differently than in the C ToolTalk
- API. The value of CALLBACK should be the name of a function of one
- argument. It will be called each time the state of the message
- changes. This is usually used to notice when the message's state
- has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
- argument values can be used.
-
- If one of the argument attributes is specified as `arg_val',
- `arg_ival', or `arg_bval', then ARGN must be the number of an
- already created argument. Arguments can be added to a message
- with `add-tooltalk-message-arg'.
-
-
- - Function: add-tooltalk-message-arg msg mode type &optional value
- Append one new argument to the message. MODE must be one of
- `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
- can be a string or an integer. ToolTalk doesn't define any
- semantics for TYPE, so only the participants in the protocol
- you're using need to agree what types mean (if anything).
- Conventionally `string' is used for strings and `int' for 32 bit
- integers. Arguments can initialized by providing a value or with
- `set-tooltalk-message-attribute'; the latter is necessary if you
- want to initialize the argument with a string that can contain
- embedded nulls (use `arg_bval').
-
-
- - Function: create-tooltalk-message
- Create a new ToolTalk message. The message's session attribute is
- initialized to the default session. Other attributes can be
- initialized with `set-tooltalk-message-attribute'.
- `make-tooltalk-message' is the preferred way to create and
- initialize a message.
-
-
- - Function: destroy-tooltalk-message msg
- Apply `tt_message_destroy' to the message. It's not necessary to
- destroy messages after they've been processed by a message or
- pattern callback, the Lisp/ToolTalk callback machinery does this
- for you.
-
-\1f
-File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
-
-Receiving Messages
-==================
-
-* Menu:
-
-* Example of Receiving Messages::
-* Elisp Interface for Receiving Messages::
-
-\1f
-File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
-
-Example of Receiving Messages
------------------------------
-
- Here's a simple example of a handler for a message that tells XEmacs
-to display a string in the mini-buffer area. The message operation is
-called `emacs-display-string'. Its first (0th) argument is the string
-to display.
-
- (defun tooltalk-display-string-handler (msg)
- (message (get-tooltalk-message-attribute msg 'arg_val 0)))
-
- (defvar display-string-pattern
- '(category TT_HANDLE
- scope TT_SESSION
- op "emacs-display-string"
- callback tooltalk-display-string-handler))
-
- (let ((p (make-tooltalk-pattern display-string-pattern)))
- (register-tooltalk-pattern p))
-
-\1f
-File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
-
-Elisp Interface for Receiving Messages
---------------------------------------
-
- - Function: make-tooltalk-pattern attributes
- Create a ToolTalk pattern and initialize its attributes. The
- value of attributes must be a list of alternating keyword/values,
- where keywords are symbols that name valid pattern attributes or
- lists of valid attributes. For example:
-
- (make-tooltalk-pattern
- '(category TT_OBSERVE
- scope TT_SESSION
- op ("operation1" "operation2")
- args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
-
- Attribute names are the same as those supported by
- `add-tooltalk-pattern-attribute', plus `'args'.
-
- Values must always be strings, integers, or symbols that represent
- ToolTalk constants or lists of same. When a list of values is
- provided all of the list elements are added to the attribute. In
- the example above, messages whose `op' attribute is `"operation1"'
- or `"operation2"' would match the pattern.
-
- The value of ARGS should be a list of pattern arguments where each
- pattern argument has the following form:
-
- `(mode [value [type]])' or just `value'
-
- Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
- a string. If TYPE isn't specified then `int' is used if VALUE is
- a number; otherwise `string' is used. If TYPE is `string' then
- VALUE is converted to a string (if it isn't a string already) with
- `prin1-to-string'. If only a value is specified then MODE
- defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
- don't need to be specified. You can find out more about the
- semantics and uses of ToolTalk pattern arguments in chapter 3 of
- the `ToolTalk Programmer's Guide'.
-
-
- - Function: register-tooltalk-pattern pat
- XEmacs will begin receiving messages that match this pattern.
-
- - Function: unregister-tooltalk-pattern pat
- XEmacs will stop receiving messages that match this pattern.
-
- - Function: add-tooltalk-pattern-attribute value pat indicator
- Add one value to the indicated pattern attribute. The names of
- attributes are the same as the ToolTalk accessors used to set them
- less the `tooltalk_pattern_' prefix and the `_add' suffix. For
- example, the name of the attribute for the
- `tt_pattern_disposition_add' attribute is `disposition'. The
- `category' attribute is handled specially, since a pattern can only
- be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
-
- Callbacks are handled slightly differently than in the C ToolTalk
- API. The value of CALLBACK should be the name of a function of one
- argument. It will be called each time the pattern matches an
- incoming message.
-
- - Function: add-tooltalk-pattern-arg pat mode type value
- Add one fully-specified argument to a ToolTalk pattern. MODE must
- be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE must be a
- string. VALUE can be an integer, string or `nil'. If VALUE is an
- integer then an integer argument (`tt_pattern_iarg_add') is added;
- otherwise a string argument is added. At present there's no way
- to add a binary data argument.
-
-
- - Function: create-tooltalk-pattern
- Create a new ToolTalk pattern and initialize its session attribute
- to be the default session.
-
- - Function: destroy-tooltalk-pattern pat
- Apply `tt_pattern_destroy' to the pattern. This effectively
- unregisters the pattern.
-
- - Function: describe-tooltalk-message msg &optional stream
- Print the message's attributes and arguments to STREAM. This is
- often useful for debugging.
-
-\1f
-File: lispref.info, Node: LDAP Support, Next: Internationalization, Prev: ToolTalk Support, Up: Top
-
-LDAP Support
-************
-
- XEmacs can be linked with a LDAP client library to provide Elisp
-primitives to access directory servers using the Lightweight Directory
-Access Protocol.
-
-* Menu:
-
-* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
-* XEmacs LDAP API:: Lisp access to LDAP functions
-* Syntax of Search Filters:: A brief summary of RFC 1558
-
-\1f
-File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
-
-Building XEmacs with LDAP support
-=================================
-
- LDAP support must be added to XEmacs at build time since it requires
-linking to an external LDAP client library. As of 21.2, XEmacs has been
-successfully built and tested with
-
- * OpenLDAP 1.0.3 (<http://www.openldap.org/>)
-
- * University of Michigan's LDAP 3.3
- (<http://www.umich.edu/~dirsvcs/ldap/>)
-
- * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
-
- Other libraries conforming to RFC 1823 will probably work also but
-may require some minor tweaking at C level.
-
- The standard XEmacs configure script autodetects an installed LDAP
-library provided the library itself and the corresponding header files
-can be found in the library and include paths. A successful detection
-will be signalled in the final output of the configure script.
-
-\1f
-File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
-
-XEmacs LDAP API
-===============
-
- XEmacs LDAP API consists of two layers: a low-level layer which
-tries to stay as close as possible to the C API (where practical) and a
-higher-level layer which provides more convenient primitives to
-effectively use LDAP.
-
- As of XEmacs 21.0, only interfaces to basic LDAP search functions are
-provided, broader support is planned in future versions.
-
-* Menu:
-
-* LDAP Variables:: Lisp variables related to LDAP
-* The High-Level LDAP API:: High-level LDAP lisp functions
-* The Low-Level LDAP API:: Low-level LDAP lisp primitives
-
-\1f
-File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
-
-LDAP Variables
---------------
-
- - Variable: ldap-default-host
- The default LDAP server hostname. A TCP port number can be
- appended to that name using a colon as a separator.
-
- - Variable: ldap-default-port
- Default TCP port for LDAP connections. Initialized from the LDAP
- library. Default value is 389.
-
- - Variable: ldap-default-base
- Default base for LDAP searches. This is a string using the syntax
- of RFC 1779. For instance, "o¬ME, cÿ" limits the search to the
- Acme organization in the United States.
-
- - Variable: ldap-host-parameters-alist
- An alist of per host options for LDAP transactions. The list
- elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
- name of an LDAP server. A TCP port number can be appended to that
- name using a colon as a separator. PROPN and VALN are
- property/value pairs describing parameters for the server. Valid
- properties:
- `binddn'
- The distinguished name of the user to bind as. This may look
- like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
-
- `passwd'
- The password to use for authentication.
-
- `auth'
- The authentication method to use, possible values depend on
- the LDAP library XEmacs was compiled with, they may include
- `simple', `krbv41' and `krbv42'.
-
- `base'
- The base for the search. This may look like `cÿ, o¬me', see
- RFC 1779 for syntax details.
-
- `scope'
- One of the symbols `base', `onelevel' or `subtree' indicating
- the scope of the search limited to a base object, to a single
- level or to the whole subtree.
-
- `deref'
- The dereference policy is one of the symbols `never',
- `always', `search' or `find' and defines how aliases are
- dereferenced.
- `never'
- Aliases are never dereferenced
-
- `always'
- Aliases are always dereferenced
-
- `search'
- Aliases are dereferenced when searching
-
- `find'
- Aliases are dereferenced when locating the base object
- for the search
-
- `timelimit'
- The timeout limit for the connection in seconds.
-
- `sizelimit'
- The maximum number of matches to return for searches
- performed on this connection.
-
-\1f
-File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
-
-The High-Level LDAP API
------------------------
-
- As of this writing the high-level Lisp LDAP API only provides for
-LDAP searches. Further support is planned in the future.
-
- The `ldap-search' function provides the most convenient interface to
-perform LDAP searches. It opens a connection to a host, performs the
-query and cleanly closes the connection thus insulating the user from
-all the details of the low-level interface such as LDAP Lisp objects
-*note The Low-Level LDAP API::
-
- - Function: ldap-search filter &optional host attributes attrsonly
- Perform an LDAP search. FILTER is the search filter *note Syntax
- of Search Filters:: HOST is the LDAP host on which to perform the
- search ATTRIBUTES is the specific attributes to retrieve, `nil'
- means retrieve all ATTRSONLY if non-`nil' retrieves the attributes
- only without their associated values. Additional search
- parameters can be specified through `ldap-host-parameters-alist'.
-
-\1f
-File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
-
-The Low-Level LDAP API
-----------------------
-
-* Menu:
-
-* The LDAP Lisp Object::
-* Opening and Closing a LDAP Connection::
-* Searching on a LDAP Server (Low-level)::
-
-\1f
-File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
-
-The LDAP Lisp Object
-....................
-
- An internal built-in `ldap' lisp object represents a LDAP connection.
-
- - Function: ldapp object
- This function returns non-`nil' if OBJECT is a `ldap' object.
-
- - Function: ldap-host ldap
- Return the server host of the connection represented by LDAP
-
- - Function: ldap-live-p ldap
- Return non-`nil' if LDAP is an active LDAP connection
-
-\1f
-File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Searching on a LDAP Server (Low-level), Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API
-
-Opening and Closing a LDAP Connection
-.....................................
-
- - Function: ldap-open host &optional plist
- Open a LDAP connection to HOST. PLIST is a property list
- containing additional parameters for the connection. Valid keys
- in that list are:
- `port'
- The TCP port to use for the connection if different from
- `ldap-default-port' or the library builtin value
-
- `auth'
- The authentication method to use, possible values depend on
- the LDAP library XEmacs was compiled with, they may include
- `simple', `krbv41' and `krbv42'.
-
- `binddn'
- The distinguished name of the user to bind as. This may look
- like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
-
- `passwd'
- The password to use for authentication.
-
- `deref'
- The dereference policy is one of the symbols `never',
- `always', `search' or `find' and defines how aliases are
- dereferenced.
- `never'
- Aliases are never dereferenced
-
- `always'
- Aliases are always dereferenced
-
- `search'
- Aliases are dereferenced when searching
-
- `find'
- Aliases are dereferenced when locating the base object
- for the search The default is `never'.
-
- `timelimit'
- The timeout limit for the connection in seconds.
-
- `sizelimit'
- The maximum number of matches to return for searches
- performed on this connection.
-
- - Function: ldap-close ldap
- Close the connection represented by LDAP
-
-\1f
-File: lispref.info, Node: Searching on a LDAP Server (Low-level), Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API
-
-Searching on a LDAP Server (Low-level)
-......................................
-
- `ldap-search-internal' is the low-level primitive to perform a
-search on a LDAP server. It works directly on an open LDAP connection
-thus requiring a preliminary call to `ldap-open'. Multiple searches
-can be made on the same connection, then the session must be closed
-with `ldap-close'.
-
- - Function: ldap-search-internal ldap filter base scope attrs attrsonly
- Perform a search on an open connection LDAP created with
- `ldap-open'. FILTER is a filter string for the search *note
- Syntax of Search Filters:: BASE is the distinguished name at which
- to start the search. SCOPE is one of the symbols `base',
- `onelevel' or `subtree' indicating the scope of the search limited
- to a base object, to a single level or to the whole subtree. The
- default is `subtree'. `attrs' is a list of strings indicating
- which attributes to retrieve for each matching entry. If `nil' all
- available attributes are returned. If `attrsonly' is non-`nil'
- then only the attributes are retrieved, not their associated values
- The function returns a list of matching entries. Each entry being
- itself an alist of attribute/values.
-
-\1f
-File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
-
-Syntax of Search Filters
-========================
-
- LDAP search functions use RFC1558 syntax to describe the search
-filter. In that syntax simple filters have the form:
-
- (<attr> <filtertype> <value>)
-
- `<attr>' is an attribute name such as `cn' for Common Name, `o' for
-Organization, etc...
-
- `<value>' is the corresponding value. This is generally an exact
-string but may also contain `*' characters as wildcards
-
- `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
-equality, approximate equality, inferiority and superiority.
-
- Thus `(cn=John Smith)' matches all records having a canonical name
-equal to John Smith.
-
- A special case is the presence filter `(<attr>=*' which matches
-records containing a particular attribute. For instance `(mail=*)'
-matches all records containing a `mail' attribute.
-
- Simple filters can be connected together with the logical operators
-`&', `|' and `!' which stand for the usual and, or and not operators.
-
- `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
-matches records of class `Person' containing a `mail' attribute and
-corresponding to people whose last name is `Smith' or whose first name
-is `John'.
-
-\1f
-File: lispref.info, Node: Internationalization, Next: MULE, Prev: LDAP Support, Up: Top
-
-Internationalization
-********************
-
-* Menu:
-
-* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
-* I18N Level 3:: Support for localized messages.
-* I18N Level 4:: Support for Asian languages.
-
-\1f
-File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
-
-I18N Levels 1 and 2
-===================
-
- XEmacs is now compliant with I18N levels 1 and 2. Specifically,
-this means that it is 8-bit clean and correctly handles time and date
-functions. XEmacs will correctly display the entire ISO-Latin 1
-character set.
-
- The compose key may now be used to create any character in the
-ISO-Latin 1 character set not directly available via the keyboard.. In
-order for the compose key to work it is necessary to load the file
-`x-compose.el'. At any time while composing a character, `C-h' will
-display all valid completions and the character which would be produced.
-
-\1f
-File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
-
-I18N Level 3
-============
-
-* Menu:
-
-* Level 3 Basics::
-* Level 3 Primitives::
-* Dynamic Messaging::
-* Domain Specification::
-* Documentation String Extraction::
-
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
-
-Level 3 Basics
---------------
-
- XEmacs now provides alpha-level functionality for I18N Level 3.
-This means that everything necessary for full messaging is available,
-but not every file has been converted.
-
- The two message files which have been created are `src/emacs.po' and
-`lisp/packages/mh-e.po'. Both files need to be converted using
-`msgfmt', and the resulting `.mo' files placed in some locale's
-`LC_MESSAGES' directory. The test "translations" in these files are
-the original messages prefixed by `TRNSLT_'.
-
- The domain for a variable is stored on the variable's property list
-under the property name VARIABLE-DOMAIN. The function
-`documentation-property' uses this information when translating a
-variable's documentation.
+File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
+
+Elisp Interface for Sending Messages
+------------------------------------
+
+ - Function: make-tooltalk-message attributes
+ Create a ToolTalk message and initialize its attributes. The
+ value of ATTRIBUTES must be a list of alternating keyword/values,
+ where keywords are symbols that name valid message attributes.
+ For example:
+
+ (make-tooltalk-message
+ '(class TT_NOTICE
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "do-something"
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants. Attribute names are the same as those
+ supported by `set-tooltalk-message-attribute', plus `args'.
+
+ The value of `args' should be a list of message arguments where
+ each message argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk message arguments in chapter 4 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: send-tooltalk-message msg
+ Send the message on its way. Once the message has been sent it's
+ almost always a good idea to get rid of it with
+ `destroy-tooltalk-message'.
+
+
+ - Function: return-tooltalk-message msg &optional mode
+ Send a reply to this message. The second argument can be `reply',
+ `reject' or `fail'; the default is `reply'. Before sending a
+ reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
+ should have been filled in--see `set-tooltalk-message-attribute'.
+
+
+ - Function: get-tooltalk-message-attribute msg attribute &optional argn
+ Returns the indicated ToolTalk message attribute. Attributes are
+ identified by symbols with the same name (underscores and all) as
+ the suffix of the ToolTalk `tt_message_<attribute>' function that
+ extracts the value. String attribute values are copied and
+ enumerated type values (except disposition) are converted to
+ symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
+ represented by fixnums (small integers), `opnum' is converted to a
+ string, and `disposition' is converted to a fixnum. We convert
+ `opnum' (a C int) to a string (e.g. `123' => `"123"') because
+ there's no guarantee that opnums will fit within the range of
+ XEmacs Lisp integers.
+
+ [TBD] Use the `plist' attribute instead of C API `user' attribute
+ for user-defined message data. To retrieve the value of a message
+ property, specify the indicator for ARGN. For example, to get the
+ value of a property called `rflag', use
+
+ (get-tooltalk-message-attribute msg 'plist 'rflag)
+
+ To get the value of a message argument use one of the `arg_val'
+ (strings), `arg_ival' (integers), or `arg_bval' (strings with
+ embedded nulls), attributes. For example, to get the integer
+ value of the third argument:
+
+ (get-tooltalk-message-attribute msg 'arg_ival 2)
+
+ As you can see, argument numbers are zero-based. The type of each
+ arguments can be retrieved with the `arg_type' attribute; however
+ ToolTalk doesn't define any semantics for the string value of
+ `arg_type'. Conventionally `string' is used for strings and `int'
+ for 32 bit integers. Note that XEmacs Lisp stores the lengths of
+ strings explicitly (unlike C) so treating the value returned by
+ `arg_bval' like a string is fine.
+
+
+ - Function: set-tooltalk-message-attribute value msg attribute
+ &optional argn
+ Initialize one ToolTalk message attribute.
+
+ Attribute names and values are the same as for
+ `get-tooltalk-message-attribute'. A property list is provided for
+ user data (instead of the `user' message attribute); see
+ `get-tooltalk-message-attribute'.
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the state of the message
+ changes. This is usually used to notice when the message's state
+ has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
+ argument values can be used.
+
+ If one of the argument attributes is specified as `arg_val',
+ `arg_ival', or `arg_bval', then ARGN must be the number of an
+ already created argument. Arguments can be added to a message
+ with `add-tooltalk-message-arg'.
+
+
+ - Function: add-tooltalk-message-arg msg mode type &optional value
+ Append one new argument to the message. MODE must be one of
+ `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
+ can be a string or an integer. ToolTalk doesn't define any
+ semantics for TYPE, so only the participants in the protocol
+ you're using need to agree what types mean (if anything).
+ Conventionally `string' is used for strings and `int' for 32 bit
+ integers. Arguments can initialized by providing a value or with
+ `set-tooltalk-message-attribute'; the latter is necessary if you
+ want to initialize the argument with a string that can contain
+ embedded nulls (use `arg_bval').
+
+
+ - Function: create-tooltalk-message
+ Create a new ToolTalk message. The message's session attribute is
+ initialized to the default session. Other attributes can be
+ initialized with `set-tooltalk-message-attribute'.
+ `make-tooltalk-message' is the preferred way to create and
+ initialize a message.
+
+
+ - Function: destroy-tooltalk-message msg
+ Apply `tt_message_destroy' to the message. It's not necessary to
+ destroy messages after they've been processed by a message or
+ pattern callback, the Lisp/ToolTalk callback machinery does this
+ for you.
\1f
-File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3
-
-Level 3 Primitives
-------------------
-
- - Function: gettext string
- This function looks up STRING in the default message domain and
- returns its translation. If `I18N3' was not enabled when XEmacs
- was compiled, it just returns STRING.
-
- - Function: dgettext domain string
- This function looks up STRING in the specified message domain and
- returns its translation. If `I18N3' was not enabled when XEmacs
- was compiled, it just returns STRING.
-
- - Function: bind-text-domain domain pathname
- This function associates a pathname with a message domain. Here's
- how the path to message file is constructed under SunOS 5.x:
-
- `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
+File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
- If `I18N3' was not enabled when XEmacs was compiled, this function
- does nothing.
+Receiving Messages
+==================
- - Special Form: domain string
- This function specifies the text domain used for translating
- documentation strings and interactive prompts of a function. For
- example, write:
-
- (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
-
- to specify `emacs-foo' as the text domain of the function `foo'.
- The "call" to `domain' is actually a declaration rather than a
- function; when actually called, `domain' just returns `nil'.
-
- - Function: domain-of function
- This function returns the text domain of FUNCTION; it returns
- `nil' if it is the default domain. If `I18N3' was not enabled
- when XEmacs was compiled, it always returns `nil'.
-
-\1f
-File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3
-
-Dynamic Messaging
------------------
+* Menu:
- The `format' function has been extended to permit you to change the
-order of parameter insertion. For example, the conversion format
-`%1$s' inserts parameter one as a string, while `%2$s' inserts
-parameter two. This is useful when creating translations which require
-you to change the word order.
+* Example of Receiving Messages::
+* Elisp Interface for Receiving Messages::
\1f
-File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3
-
-Domain Specification
---------------------
-
- The default message domain of XEmacs is `emacs'. For add-on
-packages, it is best to use a different domain. For example, let us
-say we want to convert the "gorilla" package to use the domain
-`emacs-gorilla'. To translate the message "What gorilla?", use
-`dgettext' as follows:
+File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
- (dgettext "emacs-gorilla" "What gorilla?")
-
- A function (or macro) which has a documentation string or an
-interactive prompt needs to be associated with the domain in order for
-the documentation or prompt to be translated. This is done with the
-`domain' special form as follows:
-
- (defun scratch (location)
- "Scratch the specified location."
- (domain "emacs-gorilla")
- (interactive "sScratch: ")
- ... )
-
- It is most efficient to specify the domain in the first line of the
-function body, before the `interactive' form.
-
- For variables and constants which have documentation strings,
-specify the domain after the documentation.
-
- - Special Form: defvar symbol [value [doc-string [domain]]]
- Example:
- (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
+Example of Receiving Messages
+-----------------------------
- - Special Form: defconst symbol [value [doc-string [domain]]]
- Example:
- (defconst limbs 4 "Number of limbs" "emacs-gorilla")
+ Here's a simple example of a handler for a message that tells XEmacs
+to display a string in the mini-buffer area. The message operation is
+called `emacs-display-string'. Its first (0th) argument is the string
+to display.
- Autoloaded functions which are specified in `loaddefs.el' do not need
-to have a domain specification, because their documentation strings are
-extracted into the main message base. However, for autoloaded functions
-which are specified in a separate package, use following syntax:
+ (defun tooltalk-display-string-handler (msg)
+ (message (get-tooltalk-message-attribute msg 'arg_val 0)))
+
+ (defvar display-string-pattern
+ '(category TT_HANDLE
+ scope TT_SESSION
+ op "emacs-display-string"
+ callback tooltalk-display-string-handler))
+
+ (let ((p (make-tooltalk-pattern display-string-pattern)))
+ (register-tooltalk-pattern p))
- - Function: autoload symbol filename &optional docstring interactive
- macro domain
- Example:
- (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
+\1f
+File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
+
+Elisp Interface for Receiving Messages
+--------------------------------------
+
+ - Function: make-tooltalk-pattern attributes
+ Create a ToolTalk pattern and initialize its attributes. The
+ value of attributes must be a list of alternating keyword/values,
+ where keywords are symbols that name valid pattern attributes or
+ lists of valid attributes. For example:
+
+ (make-tooltalk-pattern
+ '(category TT_OBSERVE
+ scope TT_SESSION
+ op ("operation1" "operation2")
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Attribute names are the same as those supported by
+ `add-tooltalk-pattern-attribute', plus `'args'.
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants or lists of same. When a list of values is
+ provided all of the list elements are added to the attribute. In
+ the example above, messages whose `op' attribute is `"operation1"'
+ or `"operation2"' would match the pattern.
+
+ The value of ARGS should be a list of pattern arguments where each
+ pattern argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk pattern arguments in chapter 3 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: register-tooltalk-pattern pat
+ XEmacs will begin receiving messages that match this pattern.
+
+ - Function: unregister-tooltalk-pattern pat
+ XEmacs will stop receiving messages that match this pattern.
+
+ - Function: add-tooltalk-pattern-attribute value pat indicator
+ Add one value to the indicated pattern attribute. The names of
+ attributes are the same as the ToolTalk accessors used to set them
+ less the `tooltalk_pattern_' prefix and the `_add' suffix. For
+ example, the name of the attribute for the
+ `tt_pattern_disposition_add' attribute is `disposition'. The
+ `category' attribute is handled specially, since a pattern can only
+ be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the pattern matches an
+ incoming message.
+
+ - Function: add-tooltalk-pattern-arg pat mode type value
+ Add one fully-specified argument to a ToolTalk pattern. MODE must
+ be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE must be a
+ string. VALUE can be an integer, string or `nil'. If VALUE is an
+ integer then an integer argument (`tt_pattern_iarg_add') is added;
+ otherwise a string argument is added. At present there's no way
+ to add a binary data argument.
+
+
+ - Function: create-tooltalk-pattern
+ Create a new ToolTalk pattern and initialize its session attribute
+ to be the default session.
+
+ - Function: destroy-tooltalk-pattern pat
+ Apply `tt_pattern_destroy' to the pattern. This effectively
+ unregisters the pattern.
+
+ - Function: describe-tooltalk-message msg &optional stream
+ Print the message's attributes and arguments to STREAM. This is
+ often useful for debugging.
\1f
-File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3
+File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top
-Documentation String Extraction
--------------------------------
+LDAP Support
+************
- The utility `etc/make-po' scans the file `DOC' to extract
-documentation strings and creates a message file `doc.po'. This file
-may then be inserted within `emacs.po'.
+ XEmacs can be linked with a LDAP client library to provide Elisp
+primitives to access directory servers using the Lightweight Directory
+Access Protocol.
- Currently, `make-po' is hard-coded to read from `DOC' and write to
-`doc.po'. In order to extract documentation strings from an add-on
-package, first run `make-docfile' on the package to produce the `DOC'
-file. Then run `make-po -p' with the `-p' argument to indicate that we
-are extracting documentation for an add-on package.
+* Menu:
- (The `-p' argument is a kludge to make up for a subtle difference
-between pre-loaded documentation and add-on documentation: For add-on
-packages, the final carriage returns in the strings produced by
-`make-docfile' must be ignored.)
+* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
+* XEmacs LDAP API:: Lisp access to LDAP functions
+* Syntax of Search Filters:: A brief summary of RFC 1558
\1f
-File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization
+File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
-I18N Level 4
-============
+Building XEmacs with LDAP support
+=================================
- The Asian-language support in XEmacs is called "MULE". *Note MULE::.
+ LDAP support must be added to XEmacs at build time since it requires
+linking to an external LDAP client library. As of 21.2, XEmacs has been
+successfully built and tested with
-\1f
-File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top
+ * OpenLDAP 1.0.3 (<http://www.openldap.org/>)
-MULE
-****
+ * University of Michigan's LDAP 3.3
+ (<http://www.umich.edu/~dirsvcs/ldap/>)
- "MULE" is the name originally given to the version of GNU Emacs
-extended for multi-lingual (and in particular Asian-language) support.
-"MULE" is short for "MUlti-Lingual Emacs". It was originally called
-Nemacs ("Nihon Emacs" where "Nihon" is the Japanese word for "Japan"),
-when it only provided support for Japanese. XEmacs refers to its
-multi-lingual support as "MULE support" since it is based on "MULE".
+ * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
-* Menu:
+ Other libraries conforming to RFC 1823 will probably work also but
+may require some minor tweaking at C level.
-* Internationalization Terminology::
- Definition of various internationalization terms.
-* Charsets:: Sets of related characters.
-* MULE Characters:: Working with characters in XEmacs/MULE.
-* Composite Characters:: Making new characters by overstriking other ones.
-* ISO 2022:: An international standard for charsets and encodings.
-* Coding Systems:: Ways of representing a string of chars using integers.
-* CCL:: A special language for writing fast converters.
-* Category Tables:: Subdividing charsets into groups.
-
-\1f
-File: lispref.info, Node: Internationalization Terminology, Next: Charsets, Up: MULE
-
-Internationalization Terminology
-================================
-
- In internationalization terminology, a string of text is divided up
-into "characters", which are the printable units that make up the text.
-A single character is (for example) a capital `A', the number `2', a
-Katakana character, a Kanji ideograph (an "ideograph" is a "picture"
-character, such as is used in Japanese Kanji, Chinese Hanzi, and Korean
-Hangul; typically there are thousands of such ideographs in each
-language), etc. The basic property of a character is its shape. Note
-that the same character may be drawn by two different people (or in two
-different fonts) in slightly different ways, although the basic shape
-will be the same.
-
- In some cases, the differences will be significant enough that it is
-actually possible to identify two or more distinct shapes that both
-represent the same character. For example, the lowercase letters `a'
-and `g' each have two distinct possible shapes--the `a' can optionally
-have a curved tail projecting off the top, and the `g' can be formed
-either of two loops, or of one loop and a tail hanging off the bottom.
-Such distinct possible shapes of a character are called "glyphs". The
-important characteristic of two glyphs making up the same character is
-that the choice between one or the other is purely stylistic and has no
-linguistic effect on a word (this is the reason why a capital `A' and
-lowercase `a' are different characters rather than different
-glyphs--e.g. `Aspen' is a city while `aspen' is a kind of tree).
-
- Note that "character" and "glyph" are used differently here than
-elsewhere in XEmacs.
-
- A "character set" is simply a set of related characters. ASCII, for
-example, is a set of 94 characters (or 128, if you count non-printing
-characters). Other character sets are ISO8859-1 (ASCII plus various
-accented characters and other international symbols), JISX0201 (ASCII,
-more or less, plus half-width Katakana), JISX0208 (Japanese Kanji),
-JISX0212 (a second set of less-used Japanese Kanji), GB2312 (Mainland
-Chinese Hanzi), etc.
-
- Every character set has one or more "orderings", which can be viewed
-as a way of assigning a number (or set of numbers) to each character in
-the set. For most character sets, there is a standard ordering, and in
-fact all of the character sets mentioned above define a particular
-ordering. ASCII, for example, places letters in their "natural" order,
-puts uppercase letters before lowercase letters, numbers before
-letters, etc. Note that for many of the Asian character sets, there is
-no natural ordering of the characters. The actual orderings are based
-on one or more salient characteristic, of which there are many to
-choose from--e.g. number of strokes, common radicals, phonetic
-ordering, etc.
-
- The set of numbers assigned to any particular character are called
-the character's "position codes". The number of position codes
-required to index a particular character in a character set is called
-the "dimension" of the character set. ASCII, being a relatively small
-character set, is of dimension one, and each character in the set is
-indexed using a single position code, in the range 0 through 127 (if
-non-printing characters are included) or 33 through 126 (if only the
-printing characters are considered). JISX0208, i.e. Japanese Kanji,
-has thousands of characters, and is of dimension two - every character
-is indexed by two position codes, each in the range 33 through 126.
-(Note that the choice of the range here is somewhat arbitrary.
-Although a character set such as JISX0208 defines an _ordering_ of all
-its characters, it does not define the actual mapping between numbers
-and characters. You could just as easily index the characters in
-JISX0208 using numbers in the range 0 through 93, 1 through 94, 2
-through 95, etc. The reason for the actual range chosen is so that the
-position codes match up with the actual values used in the common
-encodings.)
-
- An "encoding" is a way of numerically representing characters from
-one or more character sets into a stream of like-sized numerical values
-called "words"; typically these are 8-bit, 16-bit, or 32-bit
-quantities. If an encoding encompasses only one character set, then the
-position codes for the characters in that character set could be used
-directly. (This is the case with ASCII, and as a result, most people do
-not understand the difference between a character set and an encoding.)
-This is not possible, however, if more than one character set is to be
-used in the encoding. For example, printed Japanese text typically
-requires characters from multiple character sets--ASCII, JISX0208, and
-JISX0212, to be specific. Each of these is indexed using one or more
-position codes in the range 33 through 126, so the position codes could
-not be used directly or there would be no way to tell which character
-was meant. Different Japanese encodings handle this differently--JIS
-uses special escape characters to denote different character sets; EUC
-sets the high bit of the position codes for JISX0208 and JISX0212, and
-puts a special extra byte before each JISX0212 character; etc. (JIS,
-EUC, and most of the other encodings you will encounter are 7-bit or
-8-bit encodings. There is one common 16-bit encoding, which is Unicode;
-this strives to represent all the world's characters in a single large
-character set. 32-bit encodings are generally used internally in
-programs to simplify the code that manipulates them; however, they are
-not much used externally because they are not very space-efficient.)
-
- Encodings are classified as either "modal" or "non-modal". In a
-"modal encoding", there are multiple states that the encoding can be in,
-and the interpretation of the values in the stream depends on the
-current global state of the encoding. Special values in the encoding,
-called "escape sequences", are used to change the global state. JIS,
-for example, is a modal encoding. The bytes `ESC $ B' indicate that,
-from then on, bytes are to be interpreted as position codes for
-JISX0208, rather than as ASCII. This effect is cancelled using the
-bytes `ESC ( B', which mean "switch from whatever the current state is
-to ASCII". To switch to JISX0212, the escape sequence `ESC $ ( D'.
-(Note that here, as is common, the escape sequences do in fact begin
-with `ESC'. This is not necessarily the case, however.)
-
- A "non-modal encoding" has no global state that extends past the
-character currently being interpreted. EUC, for example, is a
-non-modal encoding. Characters in JISX0208 are encoded by setting the
-high bit of the position codes, and characters in JISX0212 are encoded
-by doing the same but also prefixing the character with the byte 0x8F.
-
- The advantage of a modal encoding is that it is generally more
-space-efficient, and is easily extendable because there are essentially
-an arbitrary number of escape sequences that can be created. The
-disadvantage, however, is that it is much more difficult to work with
-if it is not being processed in a sequential manner. In the non-modal
-EUC encoding, for example, the byte 0x41 always refers to the letter
-`A'; whereas in JIS, it could either be the letter `A', or one of the
-two position codes in a JISX0208 character, or one of the two position
-codes in a JISX0212 character. Determining exactly which one is meant
-could be difficult and time-consuming if the previous bytes in the
-string have not already been processed.
-
- Non-modal encodings are further divided into "fixed-width" and
-"variable-width" formats. A fixed-width encoding always uses the same
-number of words per character, whereas a variable-width encoding does
-not. EUC is a good example of a variable-width encoding: one to three
-bytes are used per character, depending on the character set. 16-bit
-and 32-bit encodings are nearly always fixed-width, and this is in fact
-one of the main reasons for using an encoding with a larger word size.
-The advantages of fixed-width encodings should be obvious. The
-advantages of variable-width encodings are that they are generally more
-space-efficient and allow for compatibility with existing 8-bit
-encodings such as ASCII.
-
- Note that the bytes in an 8-bit encoding are often referred to as
-"octets" rather than simply as bytes. This terminology dates back to
-the days before 8-bit bytes were universal, when some computers had
-9-bit bytes, others had 10-bit bytes, etc.
+ The standard XEmacs configure script autodetects an installed LDAP
+library provided the library itself and the corresponding header files
+can be found in the library and include paths. A successful detection
+will be signalled in the final output of the configure script.
\1f
-File: lispref.info, Node: Charsets, Next: MULE Characters, Prev: Internationalization Terminology, Up: MULE
+File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
-Charsets
-========
+XEmacs LDAP API
+===============
- A "charset" in MULE is an object that encapsulates a particular
-character set as well as an ordering of those characters. Charsets are
-permanent objects and are named using symbols, like faces.
+ XEmacs LDAP API consists of two layers: a low-level layer which
+tries to stay as close as possible to the C API (where practical) and a
+higher-level layer which provides more convenient primitives to
+effectively use LDAP.
- - Function: charsetp object
- This function returns non-`nil' if OBJECT is a charset.
+ As of XEmacs 21.0, only interfaces to basic LDAP search functions are
+provided, broader support is planned in future versions.
* Menu:
-* Charset Properties:: Properties of a charset.
-* Basic Charset Functions:: Functions for working with charsets.
-* Charset Property Functions:: Functions for accessing charset properties.
-* Predefined Charsets:: Predefined charset objects.
-
-\1f
-File: lispref.info, Node: Charset Properties, Next: Basic Charset Functions, Up: Charsets
-
-Charset Properties
-------------------
-
- Charsets have the following properties:
-
-`name'
- A symbol naming the charset. Every charset must have a different
- name; this allows a charset to be referred to using its name
- rather than the actual charset object.
-
-`doc-string'
- A documentation string describing the charset.
-
-`registry'
- A regular expression matching the font registry field for this
- character set. For example, both the `ascii' and `latin-iso8859-1'
- charsets use the registry `"ISO8859-1"'. This field is used to
- choose an appropriate font when the user gives a general font
- specification such as `-*-courier-medium-r-*-140-*', i.e. a
- 14-point upright medium-weight Courier font.
-
-`dimension'
- Number of position codes used to index a character in the
- character set. XEmacs/MULE can only handle character sets of
- dimension 1 or 2. This property defaults to 1.
-
-`chars'
- Number of characters in each dimension. In XEmacs/MULE, the only
- allowed values are 94 or 96. (There are a couple of pre-defined
- character sets, such as ASCII, that do not follow this, but you
- cannot define new ones like this.) Defaults to 94. Note that if
- the dimension is 2, the character set thus described is 94x94 or
- 96x96.
-
-`columns'
- Number of columns used to display a character in this charset.
- Only used in TTY mode. (Under X, the actual width of a character
- can be derived from the font used to display the characters.) If
- unspecified, defaults to the dimension. (This is almost always the
- correct value, because character sets with dimension 2 are usually
- ideograph character sets, which need two columns to display the
- intricate ideographs.)
-
-`direction'
- A symbol, either `l2r' (left-to-right) or `r2l' (right-to-left).
- Defaults to `l2r'. This specifies the direction that the text
- should be displayed in, and will be left-to-right for most
- charsets but right-to-left for Hebrew and Arabic. (Right-to-left
- display is not currently implemented.)
-
-`final'
- Final byte of the standard ISO 2022 escape sequence designating
- this charset. Must be supplied. Each combination of (DIMENSION,
- CHARS) defines a separate namespace for final bytes, and each
- charset within a particular namespace must have a different final
- byte. Note that ISO 2022 restricts the final byte to the range
- 0x30 - 0x7E if dimension == 1, and 0x30 - 0x5F if dimension == 2.
- Note also that final bytes in the range 0x30 - 0x3F are reserved
- for user-defined (not official) character sets. For more
- information on ISO 2022, see *Note Coding Systems::.
-
-`graphic'
- 0 (use left half of font on output) or 1 (use right half of font on
- output). Defaults to 0. This specifies how to convert the
- position codes that index a character in a character set into an
- index into the font used to display the character set. With
- `graphic' set to 0, position codes 33 through 126 map to font
- indices 33 through 126; with it set to 1, position codes 33
- through 126 map to font indices 161 through 254 (i.e. the same
- number but with the high bit set). For example, for a font whose
- registry is ISO8859-1, the left half of the font (octets 0x20 -
- 0x7F) is the `ascii' charset, while the right half (octets 0xA0 -
- 0xFF) is the `latin-iso8859-1' charset.
-
-`ccl-program'
- A compiled CCL program used to convert a character in this charset
- into an index into the font. This is in addition to the `graphic'
- property. If a CCL program is defined, the position codes of a
- character will first be processed according to `graphic' and then
- passed through the CCL program, with the resulting values used to
- index the font.
-
- This is used, for example, in the Big5 character set (used in
- Taiwan). This character set is not ISO-2022-compliant, and its
- size (94x157) does not fit within the maximum 96x96 size of
- ISO-2022-compliant character sets. As a result, XEmacs/MULE
- splits it (in a rather complex fashion, so as to group the most
- commonly used characters together) into two charset objects
- (`big5-1' and `big5-2'), each of size 94x94, and each charset
- object uses a CCL program to convert the modified position codes
- back into standard Big5 indices to retrieve a character from a
- Big5 font.
-
- Most of the above properties can only be changed when the charset is
-created. *Note Charset Property Functions::.
+* LDAP Variables:: Lisp variables related to LDAP
+* The High-Level LDAP API:: High-level LDAP lisp functions
+* The Low-Level LDAP API:: Low-level LDAP lisp primitives
\1f
-File: lispref.info, Node: Basic Charset Functions, Next: Charset Property Functions, Prev: Charset Properties, Up: Charsets
+File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
-Basic Charset Functions
------------------------
+LDAP Variables
+--------------
- - Function: find-charset charset-or-name
- This function retrieves the charset of the given name. If
- CHARSET-OR-NAME is a charset object, it is simply returned.
- Otherwise, CHARSET-OR-NAME should be a symbol. If there is no
- such charset, `nil' is returned. Otherwise the associated charset
- object is returned.
-
- - Function: get-charset name
- This function retrieves the charset of the given name. Same as
- `find-charset' except an error is signalled if there is no such
- charset instead of returning `nil'.
-
- - Function: charset-list
- This function returns a list of the names of all defined charsets.
-
- - Function: make-charset name doc-string props
- This function defines a new character set. This function is for
- use with Mule support. NAME is a symbol, the name by which the
- character set is normally referred. DOC-STRING is a string
- describing the character set. PROPS is a property list,
- describing the specific nature of the character set. The
- recognized properties are `registry', `dimension', `columns',
- `chars', `final', `graphic', `direction', and `ccl-program', as
- previously described.
-
- - Function: make-reverse-direction-charset charset new-name
- This function makes a charset equivalent to CHARSET but which goes
- in the opposite direction. NEW-NAME is the name of the new
- charset. The new charset is returned.
-
- - Function: charset-from-attributes dimension chars final &optional
- direction
- This function returns a charset with the given DIMENSION, CHARS,
- FINAL, and DIRECTION. If DIRECTION is omitted, both directions
- will be checked (left-to-right will be returned if character sets
- exist for both directions).
-
- - Function: charset-reverse-direction-charset charset
- This function returns the charset (if any) with the same dimension,
- number of characters, and final byte as CHARSET, but which is
- displayed in the opposite direction.
+ - Variable: ldap-default-host
+ The default LDAP server hostname. A TCP port number can be
+ appended to that name using a colon as a separator.
+
+ - Variable: ldap-default-port
+ Default TCP port for LDAP connections. Initialized from the LDAP
+ library. Default value is 389.
+
+ - Variable: ldap-default-base
+ Default base for LDAP searches. This is a string using the syntax
+ of RFC 1779. For instance, "o¬ME, cÿ" limits the search to the
+ Acme organization in the United States.
+
+ - Variable: ldap-host-parameters-alist
+ An alist of per host options for LDAP transactions. The list
+ elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
+ name of an LDAP server. A TCP port number can be appended to that
+ name using a colon as a separator. PROPN and VALN are
+ property/value pairs describing parameters for the server. Valid
+ properties:
+ `binddn'
+ The distinguished name of the user to bind as. This may look
+ like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
+
+ `passwd'
+ The password to use for authentication.
+
+ `auth'
+ The authentication method to use, possible values depend on
+ the LDAP library XEmacs was compiled with, they may include
+ `simple', `krbv41' and `krbv42'.
+
+ `base'
+ The base for the search. This may look like `cÿ, o¬me', see
+ RFC 1779 for syntax details.
+
+ `scope'
+ One of the symbols `base', `onelevel' or `subtree' indicating
+ the scope of the search limited to a base object, to a single
+ level or to the whole subtree.
+
+ `deref'
+ The dereference policy is one of the symbols `never',
+ `always', `search' or `find' and defines how aliases are
+ dereferenced.
+ `never'
+ Aliases are never dereferenced
+
+ `always'
+ Aliases are always dereferenced
+
+ `search'
+ Aliases are dereferenced when searching
+
+ `find'
+ Aliases are dereferenced when locating the base object
+ for the search
+
+ `timelimit'
+ The timeout limit for the connection in seconds.
+
+ `sizelimit'
+ The maximum number of matches to return for searches
+ performed on this connection.
\1f
-File: lispref.info, Node: Charset Property Functions, Next: Predefined Charsets, Prev: Basic Charset Functions, Up: Charsets
-
-Charset Property Functions
---------------------------
-
- All of these functions accept either a charset name or charset
-object.
+File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
- - Function: charset-property charset prop
- This function returns property PROP of CHARSET. *Note Charset
- Properties::.
+The High-Level LDAP API
+-----------------------
- Convenience functions are also provided for retrieving individual
-properties of a charset.
+ As of this writing the high-level Lisp LDAP API only provides for
+LDAP searches. Further support is planned in the future.
- - Function: charset-name charset
- This function returns the name of CHARSET. This will be a symbol.
+ The `ldap-search' function provides the most convenient interface to
+perform LDAP searches. It opens a connection to a host, performs the
+query and cleanly closes the connection thus insulating the user from
+all the details of the low-level interface such as LDAP Lisp objects
+*note The Low-Level LDAP API::
- - Function: charset-doc-string charset
- This function returns the doc string of CHARSET.
+ - Function: ldap-search filter &optional host attributes attrsonly
+ Perform an LDAP search. FILTER is the search filter *note Syntax
+ of Search Filters:: HOST is the LDAP host on which to perform the
+ search ATTRIBUTES is the specific attributes to retrieve, `nil'
+ means retrieve all ATTRSONLY if non-`nil' retrieves the attributes
+ only without their associated values. Additional search
+ parameters can be specified through `ldap-host-parameters-alist'.
- - Function: charset-registry charset
- This function returns the registry of CHARSET.
+\1f
+File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
- - Function: charset-dimension charset
- This function returns the dimension of CHARSET.
+The Low-Level LDAP API
+----------------------
- - Function: charset-chars charset
- This function returns the number of characters per dimension of
- CHARSET.
+* Menu:
- - Function: charset-columns charset
- This function returns the number of display columns per character
- (in TTY mode) of CHARSET.
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Searching on a LDAP Server (Low-level)::
- - Function: charset-direction charset
- This function returns the display direction of CHARSET--either
- `l2r' or `r2l'.
+\1f
+File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
- - Function: charset-final charset
- This function returns the final byte of the ISO 2022 escape
- sequence designating CHARSET.
+The LDAP Lisp Object
+....................
- - Function: charset-graphic charset
- This function returns either 0 or 1, depending on whether the
- position codes of characters in CHARSET map to the left or right
- half of their font, respectively.
+ An internal built-in `ldap' lisp object represents a LDAP connection.
- - Function: charset-ccl-program charset
- This function returns the CCL program, if any, for converting
- position codes of characters in CHARSET into font indices.
+ - Function: ldapp object
+ This function returns non-`nil' if OBJECT is a `ldap' object.
- The only property of a charset that can currently be set after the
-charset has been created is the CCL program.
+ - Function: ldap-host ldap
+ Return the server host of the connection represented by LDAP
- - Function: set-charset-ccl-program charset ccl-program
- This function sets the `ccl-program' property of CHARSET to
- CCL-PROGRAM.
+ - Function: ldap-live-p ldap
+ Return non-`nil' if LDAP is an active LDAP connection
\1f
-File: lispref.info, Node: Predefined Charsets, Prev: Charset Property Functions, Up: Charsets
-
-Predefined Charsets
--------------------
-
- The following charsets are predefined in the C code.
-
- Name Type Fi Gr Dir Registry
- --------------------------------------------------------------
- ascii 94 B 0 l2r ISO8859-1
- control-1 94 0 l2r ---
- latin-iso8859-1 94 A 1 l2r ISO8859-1
- latin-iso8859-2 96 B 1 l2r ISO8859-2
- latin-iso8859-3 96 C 1 l2r ISO8859-3
- latin-iso8859-4 96 D 1 l2r ISO8859-4
- cyrillic-iso8859-5 96 L 1 l2r ISO8859-5
- arabic-iso8859-6 96 G 1 r2l ISO8859-6
- greek-iso8859-7 96 F 1 l2r ISO8859-7
- hebrew-iso8859-8 96 H 1 r2l ISO8859-8
- latin-iso8859-9 96 M 1 l2r ISO8859-9
- thai-tis620 96 T 1 l2r TIS620
- katakana-jisx0201 94 I 1 l2r JISX0201.1976
- latin-jisx0201 94 J 0 l2r JISX0201.1976
- japanese-jisx0208-1978 94x94 @ 0 l2r JISX0208.1978
- japanese-jisx0208 94x94 B 0 l2r JISX0208.19(83|90)
- japanese-jisx0212 94x94 D 0 l2r JISX0212
- chinese-gb2312 94x94 A 0 l2r GB2312
- chinese-cns11643-1 94x94 G 0 l2r CNS11643.1
- chinese-cns11643-2 94x94 H 0 l2r CNS11643.2
- chinese-big5-1 94x94 0 0 l2r Big5
- chinese-big5-2 94x94 1 0 l2r Big5
- korean-ksc5601 94x94 C 0 l2r KSC5601
- composite 96x96 0 l2r ---
-
- The following charsets are predefined in the Lisp code.
-
- Name Type Fi Gr Dir Registry
- --------------------------------------------------------------
- arabic-digit 94 2 0 l2r MuleArabic-0
- arabic-1-column 94 3 0 r2l MuleArabic-1
- arabic-2-column 94 4 0 r2l MuleArabic-2
- sisheng 94 0 0 l2r sisheng_cwnn\|OMRON_UDC_ZH
- chinese-cns11643-3 94x94 I 0 l2r CNS11643.1
- chinese-cns11643-4 94x94 J 0 l2r CNS11643.1
- chinese-cns11643-5 94x94 K 0 l2r CNS11643.1
- chinese-cns11643-6 94x94 L 0 l2r CNS11643.1
- chinese-cns11643-7 94x94 M 0 l2r CNS11643.1
- ethiopic 94x94 2 0 l2r Ethio
- ascii-r2l 94 B 0 r2l ISO8859-1
- ipa 96 0 1 l2r MuleIPA
- vietnamese-lower 96 1 1 l2r VISCII1.1
- vietnamese-upper 96 2 1 l2r VISCII1.1
-
- For all of the above charsets, the dimension and number of columns
-are the same.
-
- Note that ASCII, Control-1, and Composite are handled specially.
-This is why some of the fields are blank; and some of the filled-in
-fields (e.g. the type) are not really accurate.
+File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Searching on a LDAP Server (Low-level), Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API
-\1f
-File: lispref.info, Node: MULE Characters, Next: Composite Characters, Prev: Charsets, Up: MULE
+Opening and Closing a LDAP Connection
+.....................................
-MULE Characters
-===============
+ - Function: ldap-open host &optional plist
+ Open a LDAP connection to HOST. PLIST is a property list
+ containing additional parameters for the connection. Valid keys
+ in that list are:
+ `port'
+ The TCP port to use for the connection if different from
+ `ldap-default-port' or the library builtin value
- - Function: make-char charset arg1 &optional arg2
- This function makes a multi-byte character from CHARSET and octets
- ARG1 and ARG2.
+ `auth'
+ The authentication method to use, possible values depend on
+ the LDAP library XEmacs was compiled with, they may include
+ `simple', `krbv41' and `krbv42'.
- - Function: char-charset ch
- This function returns the character set of char CH.
+ `binddn'
+ The distinguished name of the user to bind as. This may look
+ like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
- - Function: char-octet ch &optional n
- This function returns the octet (i.e. position code) numbered N
- (should be 0 or 1) of char CH. N defaults to 0 if omitted.
+ `passwd'
+ The password to use for authentication.
- - Function: find-charset-region start end &optional buffer
- This function returns a list of the charsets in the region between
- START and END. BUFFER defaults to the current buffer if omitted.
+ `deref'
+ The dereference policy is one of the symbols `never',
+ `always', `search' or `find' and defines how aliases are
+ dereferenced.
+ `never'
+ Aliases are never dereferenced
- - Function: find-charset-string string
- This function returns a list of the charsets in STRING.
+ `always'
+ Aliases are always dereferenced
-\1f
-File: lispref.info, Node: Composite Characters, Next: ISO 2022, Prev: MULE Characters, Up: MULE
+ `search'
+ Aliases are dereferenced when searching
-Composite Characters
-====================
+ `find'
+ Aliases are dereferenced when locating the base object
+ for the search The default is `never'.
- Composite characters are not yet completely implemented.
+ `timelimit'
+ The timeout limit for the connection in seconds.
- - Function: make-composite-char string
- This function converts a string into a single composite character.
- The character is the result of overstriking all the characters in
- the string.
+ `sizelimit'
+ The maximum number of matches to return for searches
+ performed on this connection.
- - Function: composite-char-string ch
- This function returns a string of the characters comprising a
- composite character.
-
- - Function: compose-region start end &optional buffer
- This function composes the characters in the region from START to
- END in BUFFER into one composite character. The composite
- character replaces the composed characters. BUFFER defaults to
- the current buffer if omitted.
-
- - Function: decompose-region start end &optional buffer
- This function decomposes any composite characters in the region
- from START to END in BUFFER. This converts each composite
- character into one or more characters, the individual characters
- out of which the composite character was formed. Non-composite
- characters are left as-is. BUFFER defaults to the current buffer
- if omitted.
+ - Function: ldap-close ldap
+ Close the connection represented by LDAP
\1f
-File: lispref.info, Node: ISO 2022, Next: Coding Systems, Prev: Composite Characters, Up: MULE
-
-ISO 2022
-========
+File: lispref.info, Node: Searching on a LDAP Server (Low-level), Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API
+
+Searching on a LDAP Server (Low-level)
+......................................
+
+ `ldap-search-internal' is the low-level primitive to perform a
+search on a LDAP server. It works directly on an open LDAP connection
+thus requiring a preliminary call to `ldap-open'. Multiple searches
+can be made on the same connection, then the session must be closed
+with `ldap-close'.
+
+ - Function: ldap-search-internal ldap filter base scope attrs attrsonly
+ Perform a search on an open connection LDAP created with
+ `ldap-open'. FILTER is a filter string for the search *note
+ Syntax of Search Filters:: BASE is the distinguished name at which
+ to start the search. SCOPE is one of the symbols `base',
+ `onelevel' or `subtree' indicating the scope of the search limited
+ to a base object, to a single level or to the whole subtree. The
+ default is `subtree'. `attrs' is a list of strings indicating
+ which attributes to retrieve for each matching entry. If `nil' all
+ available attributes are returned. If `attrsonly' is non-`nil'
+ then only the attributes are retrieved, not their associated values
+ The function returns a list of matching entries. Each entry being
+ itself an alist of attribute/values.
- This section briefly describes the ISO 2022 encoding standard. For
-more thorough understanding, please refer to the original document of
-ISO 2022.
+\1f
+File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
- Character sets ("charsets") are classified into the following four
-categories, according to the number of characters of charset:
-94-charset, 96-charset, 94x94-charset, and 96x96-charset.
+Syntax of Search Filters
+========================
-94-charset
- ASCII(B), left(J) and right(I) half of JISX0201, ...
+ LDAP search functions use RFC1558 syntax to describe the search
+filter. In that syntax simple filters have the form:
-96-charset
- Latin-1(A), Latin-2(B), Latin-3(C), ...
+ (<attr> <filtertype> <value>)
-94x94-charset
- GB2312(A), JISX0208(B), KSC5601(C), ...
+ `<attr>' is an attribute name such as `cn' for Common Name, `o' for
+Organization, etc...
-96x96-charset
- none for the moment
+ `<value>' is the corresponding value. This is generally an exact
+string but may also contain `*' characters as wildcards
- The character in parentheses after the name of each charset is the
-"final character" F, which can be regarded as the identifier of the
-charset. ECMA allocates F to each charset. F is in the range of
-0x30..0x7F, but 0x30..0x3F are only for private use.
+ `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
+equality, approximate equality, inferiority and superiority.
- Note: "ECMA" = European Computer Manufacturers Association
+ Thus `(cn=John Smith)' matches all records having a canonical name
+equal to John Smith.
- There are four "registers of charsets", called G0 thru G3. You can
-designate (or assign) any charset to one of these registers.
+ A special case is the presence filter `(<attr>=*' which matches
+records containing a particular attribute. For instance `(mail=*)'
+matches all records containing a `mail' attribute.
- The code space contained within one octet (of size 256) is divided
-into 4 areas: C0, GL, C1, and GR. GL and GR are the areas into which a
-register of charset can be invoked into.
+ Simple filters can be connected together with the logical operators
+`&', `|' and `!' which stand for the usual and, or and not operators.
- C0: 0x00 - 0x1F
- GL: 0x20 - 0x7F
- C1: 0x80 - 0x9F
- GR: 0xA0 - 0xFF
+ `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
+matches records of class `Person' containing a `mail' attribute and
+corresponding to people whose last name is `Smith' or whose first name
+is `John'.
- Usually, in the initial state, G0 is invoked into GL, and G1 is
-invoked into GR.
+\1f
+File: lispref.info, Node: PostgreSQL Support, Next: Internationalization, Prev: LDAP Support, Up: Top
- ISO 2022 distinguishes 7-bit environments and 8-bit environments. In
-7-bit environments, only C0 and GL are used.
+PostgreSQL Support
+******************
- Charset designation is done by escape sequences of the form:
+ XEmacs can be linked with PostgreSQL libpq run-time support to
+provide relational database access from Emacs Lisp code.
- ESC [I] I F
+* Menu:
- where I is an intermediate character in the range 0x20 - 0x2F, and F
-is the final character identifying this charset.
+* Building XEmacs with PostgreSQL support::
+* XEmacs PostgreSQL libpq API::
+* XEmacs PostgreSQL libpq Examples::
- The meaning of intermediate characters are:
+\1f
+File: lispref.info, Node: Building XEmacs with PostgreSQL support, Next: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support
+
+Building XEmacs with PostgreSQL support
+=======================================
+
+ XEmacs PostgreSQL support requires linking to the PostgreSQL libpq.so
+library. Describing how to build and install PostgreSQL is beyond the
+scope of this document, see the PostgreSQL manual for details.
+
+ If you have installed XEmacs from one of the binary kits on
+(<ftp://ftp.xemacs.org/>), or are using an XEmacs binary from a CD ROM,
+you should have XEmacs PostgreSQL support by default. If you are
+building XEmacs from source on a Linux system with PostgreSQL installed
+into the default location, it should be autodetected when you run
+configure. If you have installed PostgreSQL into its non-Linux default
+location, `/usr/local/pgsql', you must specify
+`--site-prefixes=/usr/local/pgsql' when you run configure. If you
+installed PostgreSQL into another location, use that instead of
+`/usr/local/pgsql' when specifying `--site-prefixes'.
+
+ As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported.
+XEmacs Lisp support for V7.0 is somewhat more extensive than support for
+V6.5. In particular, asynchronous queries are supported.
- $ [0x24]: indicate charset of dimension 2 (94x94 or 96x96).
- ( [0x28]: designate to G0 a 94-charset whose final byte is F.
- ) [0x29]: designate to G1 a 94-charset whose final byte is F.
- * [0x2A]: designate to G2 a 94-charset whose final byte is F.
- + [0x2B]: designate to G3 a 94-charset whose final byte is F.
- - [0x2D]: designate to G1 a 96-charset whose final byte is F.
- . [0x2E]: designate to G2 a 96-charset whose final byte is F.
- / [0x2F]: designate to G3 a 96-charset whose final byte is F.
+\1f
+File: lispref.info, Node: XEmacs PostgreSQL libpq API, Next: XEmacs PostgreSQL libpq Examples, Prev: Building XEmacs with PostgreSQL support, Up: PostgreSQL Support
+
+XEmacs PostgreSQL libpq API
+===========================
+
+ XEmacs PostgreSQL API is intended to be a policy-free, low-level
+binding to libpq. The intent is to provide all the basic functionality
+and then let high level Lisp code decide its own policies.
+
+ This documentation assumes that the reader has knowledge of SQL, but
+requires no prior knowledge of libpq.
+
+ There are many examples in this manual and some setup will be
+required. In order to run most of the following examples, the
+following code needs to be executed. In addition to the data is in
+this table, nearly all of the examples will assume that the free
+variable `P' refers to this database connection. The examples in the
+original edition of this manual were run against Postgres 7.0beta1.
+
+ (progn
+ (setq P (pq-connectdb ""))
+ ;; id is the primary key, shikona is a Japanese word that
+ ;; means `the professional name of a Sumo wrestler', and
+ ;; rank is the Sumo rank name.
+ (pq-exec P (concat "CREATE TABLE xemacs_test"
+ " (id int, shikona text, rank text);"))
+ (pq-exec P "COPY xemacs_test FROM stdin;")
+ (pq-put-line P "1\tMusashimaru\tYokuzuna\n")
+ (pq-put-line P "2\tDejima\tOozeki\n")
+ (pq-put-line P "3\tMusoyama\tSekiwake\n")
+ (pq-put-line P "4\tMiyabiyama\tSekiwake\n")
+ (pq-put-line P "5\tWakanoyama\tMaegashira\n")
+ (pq-put-line P "\\.\n")
+ (pq-end-copy P))
+ => nil
- The following rule is not allowed in ISO 2022 but can be used in
-Mule.
+* Menu:
- , [0x2C]: designate to G0 a 96-charset whose final byte is F.
+* libpq Lisp Variables::
+* libpq Lisp Symbols and DataTypes::
+* Synchronous Interface Functions::
+* Asynchronous Interface Functions::
+* Large Object Support::
+* Other libpq Functions::
+* Unimplemented libpq Functions::
- Here are examples of designations:
+\1f
+File: lispref.info, Node: libpq Lisp Variables, Next: libpq Lisp Symbols and DataTypes, Prev: XEmacs PostgreSQL libpq API, Up: XEmacs PostgreSQL libpq API
- ESC ( B : designate to G0 ASCII
- ESC - A : designate to G1 Latin-1
- ESC $ ( A or ESC $ A : designate to G0 GB2312
- ESC $ ( B or ESC $ B : designate to G0 JISX0208
- ESC $ ) C : designate to G1 KSC5601
+libpq Lisp Variables
+--------------------
- To use a charset designated to G2 or G3, and to use a charset
-designated to G1 in a 7-bit environment, you must explicitly invoke G1,
-G2, or G3 into GL. There are two types of invocation, Locking Shift
-(forever) and Single Shift (one character only).
+ Various Unix environment variables are used by libpq to provide
+defaults to the many different parameters. In the XEmacs Lisp API,
+these environment variables are bound to Lisp variables to provide more
+convenient access to Lisp Code. These variables are passed to the
+backend database server during the establishment of a database
+connection and when the `pq-setenv' call is made.
- Locking Shift is done as follows:
+ - Variable: pg:host
+ Initialized from the PGHOST environment variable. The default
+ host to connect to.
- LS0 or SI (0x0F): invoke G0 into GL
- LS1 or SO (0x0E): invoke G1 into GL
- LS2: invoke G2 into GL
- LS3: invoke G3 into GL
- LS1R: invoke G1 into GR
- LS2R: invoke G2 into GR
- LS3R: invoke G3 into GR
+ - Variable: pg:user
+ Initialized from the PGUSER environment variable. The default
+ database user name.
- Single Shift is done as follows:
+ - Variable: pg:options
+ Initialized from the PGOPTIONS environment variable. Default
+ additional server options.
- SS2 or ESC N: invoke G2 into GL
- SS3 or ESC O: invoke G3 into GL
+ - Variable: pg:port
+ Initialized from the PGPORT environment variable. The default TCP
+ port to connect to.
- (#### Ben says: I think the above is slightly incorrect. It appears
-that SS2 invokes G2 into GR and SS3 invokes G3 into GR, whereas ESC N
-and ESC O behave as indicated. The above definitions will not parse
-EUC-encoded text correctly, and it looks like the code in mule-coding.c
-has similar problems.)
+ - Variable: pg:tty
+ Initialized from the PGTTY environment variable. The default
+ debugging TTY.
- You may realize that there are a lot of ISO-2022-compliant ways of
-encoding multilingual text. Now, in the world, there exist many coding
-systems such as X11's Compound Text, Japanese JUNET code, and so-called
-EUC (Extended UNIX Code); all of these are variants of ISO 2022.
+ Compatibility note: Debugging TTYs are turned off in the XEmacs
+ Lisp binding.
- In Mule, we characterize ISO 2022 by the following attributes:
+ - Variable: pg:database
+ Initialized from the PGDATABASE environment variable. The default
+ database to connect to.
- 1. Initial designation to G0 thru G3.
+ - Variable: pg:realm
+ Initialized from the PGREALM environment variable. The default
+ Kerberos realm.
- 2. Allow designation of short form for Japanese and Chinese.
+ - Variable: pg:client-encoding
+ Initialized from the PGCLIENTENCODING environment variable. The
+ default client encoding.
- 3. Should we designate ASCII to G0 before control characters?
+ Compatibility note: This variable is not present in non-Mule
+ XEmacsen. This variable is not present in versions of libpq prior
+ to 7.0. In the current implementation, client encoding is
+ equivalent to the `file-name-coding-system' format.
- 4. Should we designate ASCII to G0 at the end of line?
+ - Variable: pg:authtype
+ Initialized from the PGAUTHTYPE environment variable. The default
+ authentication scheme used.
- 5. 7-bit environment or 8-bit environment.
+ Compatibility note: This variable is unused in versions of libpq
+ after 6.5. It is not implemented at all in the XEmacs Lisp
+ binding.
- 6. Use Locking Shift or not.
+ - Variable: pg:geqo
+ Initialized from the PGGEQO environment variable. Genetic
+ optimizer options.
- 7. Use ASCII or JIS0201-1976-Roman.
+ - Variable: pg:cost-index
+ Initialized from the PGCOSTINDEX environment variable. Cost index
+ options.
- 8. Use JISX0208-1983 or JISX0208-1976.
+ - Variable: pg:cost-heap
+ Initialized from the PGCOSTHEAP environment variable. Cost heap
+ options.
- (The last two are only for Japanese.)
+ - Variable: pg:tz
+ Initialized from the PGTZ environment variable. Default timezone.
- By specifying these attributes, you can create any variant of ISO
-2022.
+ - Variable: pg:date-style
+ Initialized from the PGDATESTYLE environment variable. Default
+ date style in returned date objects.
- Here are several examples:
+ - Variable: pg-coding-system
+ This is a variable controlling which coding system is used to
+ encode non-ASCII strings sent to the database.
- junet -- Coding system used in JUNET.
- 1. G0 <- ASCII, G1..3 <- never used
- 2. Yes.
- 3. Yes.
- 4. Yes.
- 5. 7-bit environment
- 6. No.
- 7. Use ASCII
- 8. Use JISX0208-1983
-
- ctext -- Compound Text
- 1. G0 <- ASCII, G1 <- Latin-1, G2,3 <- never used
- 2. No.
- 3. No.
- 4. Yes.
- 5. 8-bit environment
- 6. No.
- 7. Use ASCII
- 8. Use JISX0208-1983
-
- euc-china -- Chinese EUC. Although many people call this
- as "GB encoding", the name may cause misunderstanding.
- 1. G0 <- ASCII, G1 <- GB2312, G2,3 <- never used
- 2. No.
- 3. Yes.
- 4. Yes.
- 5. 8-bit environment
- 6. No.
- 7. Use ASCII
- 8. Use JISX0208-1983
-
- korean-mail -- Coding system used in Korean network.
- 1. G0 <- ASCII, G1 <- KSC5601, G2,3 <- never used
- 2. No.
- 3. Yes.
- 4. Yes.
- 5. 7-bit environment
- 6. Yes.
- 7. No.
- 8. No.
-
- Mule creates all these coding systems by default.
+ Compatibility Note: This variable is not present in InfoDock.
\1f
-File: lispref.info, Node: Coding Systems, Next: CCL, Prev: ISO 2022, Up: MULE
+File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API
-Coding Systems
-==============
+libpq Lisp Symbols and Datatypes
+--------------------------------
- A coding system is an object that defines how text containing
-multiple character sets is encoded into a stream of (typically 8-bit)
-bytes. The coding system is used to decode the stream into a series of
-characters (which may be from multiple charsets) when the text is read
-from a file or process, and is used to encode the text back into the
-same format when it is written out to a file or process.
+ The following set of symbols are used to represent the intermediate
+states involved in the asynchronous interface.
- For example, many ISO-2022-compliant coding systems (such as Compound
-Text, which is used for inter-client data under the X Window System) use
-escape sequences to switch between different charsets--Japanese Kanji,
-for example, is invoked with `ESC $ ( B'; ASCII is invoked with `ESC (
-B'; and Cyrillic is invoked with `ESC - L'. See `make-coding-system'
-for more information.
+ - Symbol: pgres::polling-failed
+ Undocumented. A fatal error has occurred during processing of an
+ asynchronous operation.
- Coding systems are normally identified using a symbol, and the
-symbol is accepted in place of the actual coding system object whenever
-a coding system is called for. (This is similar to how faces and
-charsets work.)
+ - Symbol: pgres::polling-reading
+ An intermediate status return during an asynchronous operation. It
+ indicates that one may use `select' before polling again.
- - Function: coding-system-p object
- This function returns non-`nil' if OBJECT is a coding system.
+ - Symbol: pgres::polling-writing
+ An intermediate status return during an asynchronous operation. It
+ indicates that one may use `select' before polling again.
-* Menu:
+ - Symbol: pgres::polling-ok
+ An asynchronous operation has successfully completed.
-* Coding System Types:: Classifying coding systems.
-* EOL Conversion:: Dealing with different ways of denoting
- the end of a line.
-* Coding System Properties:: Properties of a coding system.
-* Basic Coding System Functions:: Working with coding systems.
-* Coding System Property Functions:: Retrieving a coding system's properties.
-* Encoding and Decoding Text:: Encoding and decoding text.
-* Detection of Textual Encoding:: Determining how text is encoded.
-* Big5 and Shift-JIS Functions:: Special functions for these non-standard
- encodings.
+ - Symbol: pgres::polling-active
+ An intermediate status return during an asynchronous operation.
+ One can call the poll function again immediately.
-\1f
-File: lispref.info, Node: Coding System Types, Next: EOL Conversion, Up: Coding Systems
-
-Coding System Types
--------------------
-
-`nil'
-`autodetect'
- Automatic conversion. XEmacs attempts to detect the coding system
- used in the file.
-
-`no-conversion'
- No conversion. Use this for binary files and such. On output,
- graphic characters that are not in ASCII or Latin-1 will be
- replaced by a `?'. (For a no-conversion-encoded buffer, these
- characters will only be present if you explicitly insert them.)
-
-`shift-jis'
- Shift-JIS (a Japanese encoding commonly used in PC operating
- systems).
-
-`iso2022'
- Any ISO-2022-compliant encoding. Among other things, this
- includes JIS (the Japanese encoding commonly used for e-mail),
- national variants of EUC (the standard Unix encoding for Japanese
- and other languages), and Compound Text (an encoding used in X11).
- You can specify more specific information about the conversion
- with the FLAGS argument.
-
-`big5'
- Big5 (the encoding commonly used for Taiwanese).
-
-`ccl'
- The conversion is performed using a user-written pseudo-code
- program. CCL (Code Conversion Language) is the name of this
- pseudo-code.
-
-`internal'
- Write out or read in the raw contents of the memory representing
- the buffer's text. This is primarily useful for debugging
- purposes, and is only enabled when XEmacs has been compiled with
- `DEBUG_XEMACS' set (the `--debug' configure option). *Warning*:
- Reading in a file using `internal' conversion can result in an
- internal inconsistency in the memory representing a buffer's text,
- which will produce unpredictable results and may cause XEmacs to
- crash. Under normal circumstances you should never use `internal'
- conversion.
+ - Function: pq-pgconn conn field
+ CONN A database connection object. FIELD A symbol indicating
+ which field of PGconn to fetch. Possible values are shown in the
+ following table.
+ `pq::db'
+ Database name
-\1f
-File: lispref.info, Node: EOL Conversion, Next: Coding System Properties, Prev: Coding System Types, Up: Coding Systems
+ `pq::user'
+ Database user name
-EOL Conversion
---------------
+ `pq::pass'
+ Database user's password
-`nil'
- Automatically detect the end-of-line type (LF, CRLF, or CR). Also
- generate subsidiary coding systems named `NAME-unix', `NAME-dos',
- and `NAME-mac', that are identical to this coding system but have
- an EOL-TYPE value of `lf', `crlf', and `cr', respectively.
+ `pq::host'
+ Hostname database server is running on
-`lf'
- The end of a line is marked externally using ASCII LF. Since this
- is also the way that XEmacs represents an end-of-line internally,
- specifying this option results in no end-of-line conversion. This
- is the standard format for Unix text files.
+ `pq::port'
+ TCP port number used in the connection
-`crlf'
- The end of a line is marked externally using ASCII CRLF. This is
- the standard format for MS-DOS text files.
+ `pq::tty'
+ Debugging TTY
-`cr'
- The end of a line is marked externally using ASCII CR. This is the
- standard format for Macintosh text files.
+ Compatibility note: Debugging TTYs are not used in the
+ XEmacs Lisp API.
-`t'
- Automatically detect the end-of-line type but do not generate
- subsidiary coding systems. (This value is converted to `nil' when
- stored internally, and `coding-system-property' will return `nil'.)
+ `pq::options'
+ Additional server options
-\1f
-File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems
-
-Coding System Properties
-------------------------
-
-`mnemonic'
- String to be displayed in the modeline when this coding system is
- active.
-
-`eol-type'
- End-of-line conversion to be used. It should be one of the types
- listed in *Note EOL Conversion::.
-
-`post-read-conversion'
- Function called after a file has been read in, to perform the
- decoding. Called with two arguments, BEG and END, denoting a
- region of the current buffer to be decoded.
-
-`pre-write-conversion'
- Function called before a file is written out, to perform the
- encoding. Called with two arguments, BEG and END, denoting a
- region of the current buffer to be encoded.
-
- The following additional properties are recognized if TYPE is
-`iso2022':
-
-`charset-g0'
-`charset-g1'
-`charset-g2'
-`charset-g3'
- The character set initially designated to the G0 - G3 registers.
- The value should be one of
-
- * A charset object (designate that character set)
-
- * `nil' (do not ever use this register)
-
- * `t' (no character set is initially designated to the
- register, but may be later on; this automatically sets the
- corresponding `force-g*-on-output' property)
-
-`force-g0-on-output'
-`force-g1-on-output'
-`force-g2-on-output'
-`force-g3-on-output'
- If non-`nil', send an explicit designation sequence on output
- before using the specified register.
-
-`short'
- If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $
- B' on output in place of the full designation sequences `ESC $ (
- @', `ESC $ ( A', and `ESC $ ( B'.
-
-`no-ascii-eol'
- If non-`nil', don't designate ASCII to G0 at each end of line on
- output. Setting this to non-`nil' also suppresses other
- state-resetting that normally happens at the end of a line.
-
-`no-ascii-cntl'
- If non-`nil', don't designate ASCII to G0 before control chars on
- output.
-
-`seven'
- If non-`nil', use 7-bit environment on output. Otherwise, use
- 8-bit environment.
-
-`lock-shift'
- If non-`nil', use locking-shift (SO/SI) instead of single-shift or
- designation by escape sequence.
-
-`no-iso6429'
- If non-`nil', don't use ISO6429's direction specification.
-
-`escape-quoted'
- If non-nil, literal control characters that are the same as the
- beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in
- particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3
- (0x8F), and CSI (0x9B)) are "quoted" with an escape character so
- that they can be properly distinguished from an escape sequence.
- (Note that doing this results in a non-portable encoding.) This
- encoding flag is used for byte-compiled files. Note that ESC is a
- good choice for a quoting character because there are no escape
- sequences whose second byte is a character from the Control-0 or
- Control-1 character sets; this is explicitly disallowed by the ISO
- 2022 standard.
-
-`input-charset-conversion'
- A list of conversion specifications, specifying conversion of
- characters in one charset to another when decoding is performed.
- Each specification is a list of two elements: the source charset,
- and the destination charset.
-
-`output-charset-conversion'
- A list of conversion specifications, specifying conversion of
- characters in one charset to another when encoding is performed.
- The form of each specification is the same as for
- `input-charset-conversion'.
-
- The following additional properties are recognized (and required) if
-TYPE is `ccl':
-
-`decode'
- CCL program used for decoding (converting to internal format).
-
-`encode'
- CCL program used for encoding (converting to external format).
+ `pq::status'
+ Connection status. Possible return values are shown in the
+ following table.
+ `pg::connection-ok'
+ The normal, connected status.
-\1f
-File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems
+ `pg::connection-bad'
+ The connection is not open and the PGconn object needs
+ to be deleted by `pq-finish'.
-Basic Coding System Functions
------------------------------
+ `pg::connection-started'
+ An asynchronous connection has been started, but is not
+ yet complete.
- - Function: find-coding-system coding-system-or-name
- This function retrieves the coding system of the given name.
+ `pg::connection-made'
+ An asynchronous connect has been made, and there is data
+ waiting to be sent.
- If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply
- returned. Otherwise, CODING-SYSTEM-OR-NAME should be a symbol.
- If there is no such coding system, `nil' is returned. Otherwise
- the associated coding system object is returned.
+ `pg::connection-awaiting-response'
+ Awaiting data from the backend during an asynchronous
+ connection.
- - Function: get-coding-system name
- This function retrieves the coding system of the given name. Same
- as `find-coding-system' except an error is signalled if there is no
- such coding system instead of returning `nil'.
+ `pg::connection-auth-ok'
+ Received authentication, waiting for the backend to
+ start up.
- - Function: coding-system-list
- This function returns a list of the names of all defined coding
- systems.
+ `pg::connection-setenv'
+ Negotiating environment during an asynchronous
+ connection.
- - Function: coding-system-name coding-system
- This function returns the name of the given coding system.
+ `pq::error-message'
+ The last error message that was delivered to this connection.
- - Function: make-coding-system name type &optional doc-string props
- This function registers symbol NAME as a coding system.
+ `pq::backend-pid'
+ The process ID of the backend database server.
- TYPE describes the conversion method used and should be one of the
- types listed in *Note Coding System Types::.
+ The `PGresult' object is used by libpq to encapsulate the results of
+queries. The printed representation takes on four forms. When the
+PGresult object contains tuples from an SQL `SELECT' it will look like:
- DOC-STRING is a string describing the coding system.
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
- PROPS is a property list, describing the specific nature of the
- character set. Recognized properties are as in *Note Coding
- System Properties::.
+ The number in brackets indicates how many rows of data are available.
+When the PGresult object is the result of a command query that doesn't
+return anything, it will look like:
- - Function: copy-coding-system old-coding-system new-name
- This function copies OLD-CODING-SYSTEM to NEW-NAME. If NEW-NAME
- does not name an existing coding system, a new one will be created.
+ (pq-exec P "CREATE TABLE a_new_table (i int);")
+ => #<PGresult PGRES_COMMAND_OK - CREATE>
- - Function: subsidiary-coding-system coding-system eol-type
- This function returns the subsidiary coding system of
- CODING-SYSTEM with eol type EOL-TYPE.
+ When either the query is a command-type query that can affect a
+number of different rows, but doesn't return any of them it will look
+like:
+
+ (progn
+ (pq-exec P "INSERT INTO a_new_table VALUES (1);")
+ (pq-exec P "INSERT INTO a_new_table VALUES (2);")
+ (pq-exec P "INSERT INTO a_new_table VALUES (3);")
+ (setq R (pq-exec P "DELETE FROM a_new_table;")))
+ => #<PGresult PGRES_COMMAND_OK[3] - DELETE 3>
+
+ Lastly, when the underlying PGresult object has been deallocated
+directly by `pq-clear' the printed representation will look like:
+
+ (progn
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ (pq-clear R)
+ R)
+ => #<PGresult DEAD>
+
+ The following set of functions are accessors to various data in the
+PGresult object.
+
+ - Function: pq-result-status result
+ Return status of a query result. RESULT is a PGresult object.
+ The return value is one of the symbols in the following table.
+ `pgres::empty-query'
+ A query contained no text. This is usually the result of a
+ recoverable error, or a minor programming error.
+
+ `pgres::command-ok'
+ A query command that doesn't return anything was executed
+ properly by the backend.
+
+ `pgres::tuples-ok'
+ A query command that returns tuples was executed properly by
+ the backend.
+
+ `pgres::copy-out'
+ Copy Out data transfer is in progress.
+
+ `pgres::copy-in'
+ Copy In data transfer is in progress.
+
+ `pgres::bad-response'
+ An unexpected response was received from the backend.
+
+ `pgres::nonfatal-error'
+ Undocumented. This value is returned when the libpq function
+ `PQresultStatus' is called with a NULL pointer.
+
+ `pgres::fatal-error'
+ Undocumented. An error has occurred in processing the query
+ and the operation was not completed.
+
+ - Function: pq-res-status result
+ Return the query result status as a string, not a symbol. RESULT
+ is a PGresult object.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (pq-res-status R)
+ => "PGRES_TUPLES_OK"
+
+ - Function: pq-result-error-message result
+ Return an error message generated by the query, if any. RESULT is
+ a PGresult object.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs-test;"))
+ => <A fatal error is signaled in the echo area>
+ (pq-result-error-message R)
+ => "ERROR: parser: parse error at or near \"-\"
+ "
+
+ - Function: pq-ntuples result
+ Return the number of tuples in the query result. RESULT is a
+ PGresult object.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (pq-ntuples R)
+ => 5
+
+ - Function: pq-nfields result
+ Return the number of fields in each tuple of the query result.
+ RESULT is a PGresult object.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (pq-nfields R)
+ => 3
+
+ - Function: pq-binary-tuples result
+ Returns t if binary tuples are present in the results, nil
+ otherwise. RESULT is a PGresult object.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (pq-binary-tuples R)
+ => nil
+
+ - Function: pq-fname result field-index
+ Returns the name of a specific field. RESULT is a PGresult object.
+ FIELD-INDEX is the number of the column to select from. The first
+ column is number zero.
+
+ (let (i l)
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ (setq i (pq-nfields R))
+ (while (>= (decf i) 0)
+ (push (pq-fname R i) l))
+ l)
+ => ("id" "shikona" "rank")
+
+ - Function: pq-fnumber result field-name
+ Return the field number corresponding to the given field name. -1
+ is returned on a bad field name. RESULT is a PGresult object.
+ FIELD-NAME is a string representing the field name to find.
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (pq-fnumber R "id")
+ => 0
+ (pq-fnumber R "Not a field")
+ => -1
+
+ - Function: pq-ftype result field-num
+ Return an integer code representing the data type of the specified
+ column. RESULT is a PGresult object. FIELD-NUM is the field
+ number.
+
+ The return value of this function is the Object ID (Oid) in the
+ database of the type. Further queries need to be made to various
+ system tables in order to convert this value into something useful.
+
+ - Function: pq-fmod result field-num
+ Return the type modifier code associated with a field. Field
+ numbers start at zero. RESULT is a PGresult object. FIELD-INDEX
+ selects which field to use.
+
+ - Function: pq-fsize result field-index
+ Return size of the given field. RESULT is a PGresult object.
+ FIELD-INDEX selects which field to use.
+
+ (let (i l)
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ (setq i (pq-nfields R))
+ (while (>= (decf i) 0)
+ (push (list (pq-ftype R i) (pq-fsize R i)) l))
+ l)
+ => ((23 23) (25 25) (25 25))
+
+ - Function: pq-get-value result tup-num field-num
+ Retrieve a return value. RESULT is a PGresult object. TUP-NUM
+ selects which tuple to fetch from. FIELD-NUM selects which field
+ to fetch from.
+
+ Both tuples and fields are numbered from zero.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (pq-get-value R 0 1)
+ => "Musashimaru"
+ (pq-get-value R 1 1)
+ => "Dejima"
+ (pq-get-value R 2 1)
+ => "Musoyama"
+
+ - Function: pq-get-length result tup-num field-num
+ Return the length of a specific value. RESULT is a PGresult
+ object. TUP-NUM selects which tuple to fetch from. FIELD-NUM
+ selects which field to fetch from.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (pq-get-length R 0 1)
+ => 11
+ (pq-get-length R 1 1)
+ => 6
+ (pq-get-length R 2 1)
+ => 8
+
+ - Function: pq-get-is-null result tup-num field-num
+ Return t if the specific value is the SQL NULL. RESULT is a
+ PGresult object. TUP-NUM selects which tuple to fetch from.
+ FIELD-NUM selects which field to fetch from.
+
+ - Function: pq-cmd-status result
+ Return a summary string from the query. RESULT is a PGresult
+ object.
+ (pq-exec P "INSERT INTO xemacs_test
+ VALUES (6, 'Wakanohana', 'Yokozuna');")
+ => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
+ (pq-cmd-status R)
+ => "INSERT 542086 1"
+ (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired'
+ WHERE shikona='Wakanohana';"))
+ => #<PGresult PGRES_COMMAND_OK[1] - UPDATE 1>
+ (pq-cmd-status R)
+ => "UPDATE 1"
+
+ Note that the first number returned from an insertion, like in the
+ example, is an object ID number and will almost certainly vary from
+ system to system since object ID numbers in Postgres must be unique
+ across all databases.
+
+ - Function: pq-cmd-tuples result
+ Return the number of tuples if the last command was an
+ INSERT/UPDATE/DELETE. If the last command was something else, the
+ empty string is returned. RESULT is a PGresult object.
+
+ (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
+ (7, 'Takanohana', 'Yokuzuna');"))
+ => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
+ (pq-cmd-tuples R)
+ => "1"
+ (setq R (pq-exec P "SELECT * from xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
+ (pq-cmd-tuples R)
+ => ""
+ (setq R (pq-exec P "DELETE FROM xemacs_test
+ WHERE shikona LIKE '%hana';"))
+ => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
+ (pq-cmd-tuples R)
+ => "2"
+
+ - Function: pq-oid-value result
+ Return the object id of the insertion if the last command was an
+ INSERT. 0 is returned if the last command was not an insertion.
+ RESULT is a PGresult object.
+
+ In the first example, the numbers you will see on your local
+ system will almost certainly be different, however the second
+ number from the right in the unprintable PGresult object and the
+ number returned by `pq-oid-value' should match.
+ (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
+ (8, 'Terao', 'Maegashira');"))
+ => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542089 1>
+ (pq-oid-value R)
+ => 542089
+ (setq R (pq-exec P "SELECT shikona FROM xemacs_test
+ WHERE rank='Maegashira';"))
+ => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
+ (pq-oid-value R)
+ => 0
+
+ - Function: pq-make-empty-pgresult conn status
+ Create an empty pgresult with the given status. CONN a database
+ connection object STATUS a value that can be returned by
+ `pq-result-status'.
+
+ The caller is responsible for making sure the return value gets
+ properly freed.
\1f
-File: lispref.info, Node: Coding System Property Functions, Next: Encoding and Decoding Text, Prev: Basic Coding System Functions, Up: Coding Systems
-
-Coding System Property Functions
---------------------------------
+File: lispref.info, Node: Synchronous Interface Functions, Next: Asynchronous Interface Functions, Prev: libpq Lisp Symbols and DataTypes, Up: XEmacs PostgreSQL libpq API
- - Function: coding-system-doc-string coding-system
- This function returns the doc string for CODING-SYSTEM.
-
- - Function: coding-system-type coding-system
- This function returns the type of CODING-SYSTEM.
-
- - Function: coding-system-property coding-system prop
- This function returns the PROP property of CODING-SYSTEM.
+Synchronous Interface Functions
+-------------------------------
-\1f
-File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textual Encoding, Prev: Coding System Property Functions, Up: Coding Systems
-
-Encoding and Decoding Text
---------------------------
-
- - Function: decode-coding-region start end coding-system &optional
- buffer
- This function decodes the text between START and END which is
- encoded in CODING-SYSTEM. This is useful if you've read in
- encoded text from a file without decoding it (e.g. you read in a
- JIS-formatted file but used the `binary' or `no-conversion' coding
- system, so that it shows up as `^[$B!<!+^[(B'). The length of the
- encoded text is returned. BUFFER defaults to the current buffer
- if unspecified.
-
- - Function: encode-coding-region start end coding-system &optional
- buffer
- This function encodes the text between START and END using
- CODING-SYSTEM. This will, for example, convert Japanese
- characters into stuff such as `^[$B!<!+^[(B' if you use the JIS
- encoding. The length of the encoded text is returned. BUFFER
- defaults to the current buffer if unspecified.
+ - Function: pq-connectdb conninfo
+ Establish a (synchronous) database connection. CONNINFO A string
+ of blank separated options. Options are of the form "OPTION =
+ VALUE". If VALUE contains blanks, it must be single quoted.
+ Blanks around the equal sign are optional. Multiple option
+ assignments are blank separated.
+ (pq-connectdb "dbname=japanese port = 25432")
+ => #<PGconn localhost:25432 steve/japanese>
+ The printed representation of a database connection object has four
+ fields. The first field is the hostname where the database server
+ is running (in this case localhost), the second field is the port
+ number, the third field is the database user name, and the fourth
+ field is the name of the database.
+
+ Database connection objects which have been disconnected and will
+ generate an immediate error if they are used look like:
+ #<PGconn BAD>
+ Bad connections can be reestablished with `pq-reset', or deleted
+ entirely with `pq-finish'.
+
+ A database connection object that has been deleted looks like:
+ (let ((P1 (pq-connectdb "")))
+ (pq-finish P1)
+ P1)
+ => #<PGconn DEAD>
+
+ Note that database connection objects are the most heavy weight
+ objects in XEmacs Lisp at this writing, usually representing as
+ much as several megabytes of virtual memory on the machine the
+ database server is running on. It is wisest to explicitly delete
+ them when you are finished with them, rather than letting garbage
+ collection do it. An example idiom is:
+
+ (let ((P (pq-connectiondb "")))
+ (unwind-protect
+ (progn
+ (...)) ; access database here
+ (pq-finish P)))
+
+ The following options are available in the options string:
+ `authtype'
+ Authentication type. Same as PGAUTHTYPE. This is no longer
+ used.
+
+ `user'
+ Database user name. Same as PGUSER.
+
+ `password'
+ Database password.
+
+ `dbname'
+ Database name. Same as PGDATABASE
+
+ `host'
+ Symbolic hostname. Same as PGHOST.
+
+ `hostaddr'
+ Host address as four octets (eg. like 192.168.1.1).
+
+ `port'
+ TCP port to connect to. Same as PGPORT.
+
+ `tty'
+ Debugging TTY. Same as PGTTY. This value is suppressed in
+ the XEmacs Lisp API.
+
+ `options'
+ Extra backend database options. Same as PGOPTIONS. A
+ database connection object is returned regardless of whether a
+ connection was established or not.
+
+ - Function: pq-reset conn
+ Reestablish database connection. CONN A database connection
+ object.
+
+ This function reestablishes a database connection using the
+ original connection parameters. This is useful if something has
+ happened to the TCP link and it has become broken.
+
+ - Function: pq-exec conn query
+ Make a synchronous database query. CONN A database connection
+ object. QUERY A string containing an SQL query. A PGresult
+ object is returned, which in turn may be queried by its many
+ accessor functions to retrieve state out of it. If the query
+ string contains multiple SQL commands, only results from the final
+ command are returned.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;
+ DELETE FROM xemacs_test WHERE id=8;"))
+ => #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>
+
+ - Function: pq-notifies conn
+ Return the latest async notification that has not yet been handled.
+ CONN A database connection object. If there has been a
+ notification, then a list of two elements will be returned. The
+ first element contains the relation name being notified, the second
+ element contains the backend process ID number. nil is returned
+ if there aren't any notifications to process.
+
+ - Function: PQsetenv conn
+ Synchronous transfer of environment variables to a backend CONN A
+ database connection object.
+
+ Environment variable transfer is done as a normal part of database
+ connection.
+
+ Compatibility note: This function was present but not documented
+ in versions of libpq prior to 7.0.
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Detection of Textual Encoding, Next: Big5 and Shift-JIS Functions, Prev: Encoding and Decoding Text, Up: Coding Systems
+File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
-Detection of Textual Encoding
------------------------------
+Asynchronous Interface Functions
+--------------------------------
- - Function: coding-category-list
- This function returns a list of all recognized coding categories.
+ Making command by command examples is too complex with the
+asynchronous interface functions. See the examples section for
+complete calling sequences.
- - Function: set-coding-priority-list list
- This function changes the priority order of the coding categories.
- LIST should be a list of coding categories, in descending order of
- priority. Unspecified coding categories will be lower in priority
- than all specified ones, in the same relative order they were in
- previously.
+ - Function: pq-connect-start conninfo
+ Begin establishing an asynchronous database connection. CONNINFO
+ A string containing the connection options. See the documentation
+ of `pq-connectdb' for a listing of all the available flags.
- - Function: coding-priority-list
- This function returns a list of coding categories in descending
- order of priority.
+ - Function: pq-connect-poll conn
+ An intermediate function to be called during an asynchronous
+ database connection. CONN A database connection object. The
+ result codes are documented in a previous section.
- - Function: set-coding-category-system coding-category coding-system
- This function changes the coding system associated with a coding
- category.
+ - Function: pq-is-busy conn
+ Returns t if `pq-get-result' would block waiting for input. CONN
+ A database connection object.
- - Function: coding-category-system coding-category
- This function returns the coding system associated with a coding
- category.
+ - Function: pq-consume-input conn
+ Consume any available input from the backend. CONN A database
+ connection object.
- - Function: detect-coding-region start end &optional buffer
- This function detects coding system of the text in the region
- between START and END. Returned value is a list of possible coding
- systems ordered by priority. If only ASCII characters are found,
- it returns `autodetect' or one of its subsidiary coding systems
- according to a detected end-of-line type. Optional arg BUFFER
- defaults to the current buffer.
+ Nil is returned if anything bad happens.
-\1f
-File: lispref.info, Node: Big5 and Shift-JIS Functions, Prev: Detection of Textual Encoding, Up: Coding Systems
+ - Function: pq-reset-start conn
+ Reset connection to the backend asynchronously. CONN A database
+ connection object.
+
+ - Function: pq-reset-poll conn
+ Poll an asynchronous reset for completion CONN A database
+ connection object.
+
+ - Function: pq-reset-cancel conn
+ Attempt to request cancellation of the current operation. CONN A
+ database connection object.
+
+ The return value is t if the cancel request was successfully
+ dispatched, nil if not (in which case conn->errorMessage is set).
+ Note: successful dispatch is no guarantee that there will be any
+ effect at the backend. The application must read the operation
+ result as usual.
+
+ - Function: pq-send-query conn query
+ Submit a query to Postgres and don't wait for the result. CONN A
+ database connection object. Returns: t if successfully submitted
+ nil if error (conn->errorMessage is set)
+
+ - Function: pq-get-result conn
+ Retrieve an asynchronous result from a query. CONN A database
+ connection object.
+
+ NIL is returned when no more query work remains.
+
+ - Function: pq-set-nonblocking conn arg
+ Sets the PGconn's database connection non-blocking if the arg is
+ TRUE or makes it non-blocking if the arg is FALSE, this will not
+ protect you from PQexec(), you'll only be safe when using the
+ non-blocking API. CONN A database connection object.
-Big5 and Shift-JIS Functions
-----------------------------
+ - Function: pq-is-nonblocking conn
+ Return the blocking status of the database connection CONN A
+ database connection object.
- These are special functions for working with the non-standard
-Shift-JIS and Big5 encodings.
+ - Function: pq-flush conn
+ Force the write buffer to be written (or at least try) CONN A
+ database connection object.
- - Function: decode-shift-jis-char code
- This function decodes a JISX0208 character of Shift-JIS
- coding-system. CODE is the character code in Shift-JIS as a cons
- of type bytes. The corresponding character is returned.
+ - Function: PQsetenvStart conn
+ Start asynchronously passing environment variables to a backend.
+ CONN A database connection object.
- - Function: encode-shift-jis-char ch
- This function encodes a JISX0208 character CH to SHIFT-JIS
- coding-system. The corresponding character code in SHIFT-JIS is
- returned as a cons of two bytes.
+ Compatibility note: this function is only available with libpq-7.0.
- - Function: decode-big5-char code
- This function decodes a Big5 character CODE of BIG5 coding-system.
- CODE is the character code in BIG5. The corresponding character
- is returned.
+ - Function: PQsetenvPoll conn
+ Check an asynchronous enviroment variables transfer for completion.
+ CONN A database connection object.
- - Function: encode-big5-char ch
- This function encodes the Big5 character CHAR to BIG5
- coding-system. The corresponding character code in Big5 is
- returned.
+ Compatibility note: this function is only available with libpq-7.0.
+
+ - Function: PQsetenvAbort conn
+ Attempt to terminate an asynchronous environment variables
+ transfer. CONN A database connection object.
+
+ Compatibility note: this function is only available with libpq-7.0.
\1f
-File: lispref.info, Node: CCL, Next: Category Tables, Prev: Coding Systems, Up: MULE
-
-CCL
-===
-
- CCL (Code Conversion Language) is a simple structured programming
-language designed for character coding conversions. A CCL program is
-compiled to CCL code (represented by a vector of integers) and executed
-by the CCL interpreter embedded in Emacs. The CCL interpreter
-implements a virtual machine with 8 registers called `r0', ..., `r7', a
-number of control structures, and some I/O operators. Take care when
-using registers `r0' (used in implicit "set" statements) and especially
-`r7' (used internally by several statements and operations, especially
-for multiple return values and I/O operations).
-
- CCL is used for code conversion during process I/O and file I/O for
-non-ISO2022 coding systems. (It is the only way for a user to specify a
-code conversion function.) It is also used for calculating the code
-point of an X11 font from a character code. However, since CCL is
-designed as a powerful programming language, it can be used for more
-generic calculation where efficiency is demanded. A combination of
-three or more arithmetic operations can be calculated faster by CCL than
-by Emacs Lisp.
-
- *Warning:* The code in `src/mule-ccl.c' and
-`$packages/lisp/mule-base/mule-ccl.el' is the definitive description of
-CCL's semantics. The previous version of this section contained
-several typos and obsolete names left from earlier versions of MULE,
-and many may remain. (I am not an experienced CCL programmer; the few
-who know CCL well find writing English painful.)
-
- A CCL program transforms an input data stream into an output data
-stream. The input stream, held in a buffer of constant bytes, is left
-unchanged. The buffer may be filled by an external input operation,
-taken from an Emacs buffer, or taken from a Lisp string. The output
-buffer is a dynamic array of bytes, which can be written by an external
-output operation, inserted into an Emacs buffer, or returned as a Lisp
-string.
-
- A CCL program is a (Lisp) list containing two or three members. The
-first member is the "buffer magnification", which indicates the
-required minimum size of the output buffer as a multiple of the input
-buffer. It is followed by the "main block" which executes while there
-is input remaining, and an optional "EOF block" which is executed when
-the input is exhausted. Both the main block and the EOF block are CCL
-blocks.
-
- A "CCL block" is either a CCL statement or list of CCL statements.
-A "CCL statement" is either a "set statement" (either an integer or an
-"assignment", which is a list of a register to receive the assignment,
-an assignment operator, and an expression) or a "control statement" (a
-list starting with a keyword, whose allowable syntax depends on the
-keyword).
+File: lispref.info, Node: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
-* Menu:
+Large Object Support
+--------------------
+
+ - Function: pq-lo-import conn filename
+ Import a file as a large object into the database. CONN a
+ database connection object FILENAME filename to import
+
+ On success, the object id is returned.
-* CCL Syntax:: CCL program syntax in BNF notation.
-* CCL Statements:: Semantics of CCL statements.
-* CCL Expressions:: Operators and expressions in CCL.
-* Calling CCL:: Running CCL programs.
-* CCL Examples:: The encoding functions for Big5 and KOI-8.
+ - Function: pq-lo-export conn oid filename
+ Copy a large object in the database into a file. CONN a database
+ connection object. OID object id number of a large object.
+ FILENAME filename to export to.
\1f
-File: lispref.info, Node: CCL Syntax, Next: CCL Statements, Prev: CCL, Up: CCL
-
-CCL Syntax
-----------
-
- The full syntax of a CCL program in BNF notation:
-
-CCL_PROGRAM :=
- (BUFFER_MAGNIFICATION
- CCL_MAIN_BLOCK
- [ CCL_EOF_BLOCK ])
-
-BUFFER_MAGNIFICATION := integer
-CCL_MAIN_BLOCK := CCL_BLOCK
-CCL_EOF_BLOCK := CCL_BLOCK
-
-CCL_BLOCK :=
- STATEMENT | (STATEMENT [STATEMENT ...])
-STATEMENT :=
- SET | IF | BRANCH | LOOP | REPEAT | BREAK | READ | WRITE
- | CALL | END
-
-SET :=
- (REG = EXPRESSION)
- | (REG ASSIGNMENT_OPERATOR EXPRESSION)
- | integer
-
-EXPRESSION := ARG | (EXPRESSION OPERATOR ARG)
-
-IF := (if EXPRESSION CCL_BLOCK [CCL_BLOCK])
-BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
-LOOP := (loop STATEMENT [STATEMENT ...])
-BREAK := (break)
-REPEAT :=
- (repeat)
- | (write-repeat [REG | integer | string])
- | (write-read-repeat REG [integer | ARRAY])
-READ :=
- (read REG ...)
- | (read-if (REG OPERATOR ARG) CCL_BLOCK CCL_BLOCK)
- | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
-WRITE :=
- (write REG ...)
- | (write EXPRESSION)
- | (write integer) | (write string) | (write REG ARRAY)
- | string
-CALL := (call ccl-program-name)
-END := (end)
-
-REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
-ARG := REG | integer
-OPERATOR :=
- + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
- | < | > | == | <= | >= | != | de-sjis | en-sjis
-ASSIGNMENT_OPERATOR :=
- += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
-ARRAY := '[' integer ... ']'
+File: lispref.info, Node: Other libpq Functions, Next: Unimplemented libpq Functions, Prev: Large Object Support, Up: XEmacs PostgreSQL libpq API
+
+Other libpq Functions
+---------------------
+
+ - Function: pq-finish conn
+ Destroy a database connection object by calling free on it. CONN
+ a database connection object
+
+ It is possible to not call this routine because the usual XEmacs
+ garbage collection mechanism will call the underlying libpq
+ routine whenever it is releasing stale `PGconn' objects. However,
+ this routine is useful in `unwind-protect' clauses to make
+ connections go away quickly when unrecoverable errors have
+ occurred.
+
+ After calling this routine, the printed representation of the
+ XEmacs wrapper object will contain the string "DEAD".
+
+ - Function: pq-client-encoding conn
+ Return the client encoding as an integer code. CONN a database
+ connection object
+
+ (pq-client-encoding P)
+ => 1
+
+ Compatibility note: This function did not exist prior to libpq-7.0
+ and does not exist in a non-Mule XEmacs.
+
+ - Function: pq-set-client-encoding conn encoding
+ Set client coding system. CONN a database connection object
+ ENCODING a string representing the desired coding system
+
+ (pq-set-client-encoding P "EUC_JP")
+ => 0
+
+ The current idiom for ensuring proper coding system conversion is
+ the following (illustrated for EUC Japanese encoding):
+ (setq P (pq-connectdb "..."))
+ (let ((file-name-coding-system 'euc-jp)
+ (pg-coding-system 'euc-jp))
+ (pq-set-client-encoding "EUC_JP")
+ ...)
+ (pq-finish P)
+ Compatibility note: This function did not exist prior to libpq-7.0
+ and does not exist in a non-Mule XEmacs.
+
+ - Function: pq-env-2-encoding
+ Return the integer code representing the coding system in
+ PGCLIENTENCODING.
+
+ (pq-env-2-encoding)
+ => 0
+ Compatibility note: This function did not exist prior to libpq-7.0
+ and does not exist in a non-Mule XEmacs.
+
+ - Function: pq-clear res
+ Destroy a query result object by calling free() on it. RES a
+ query result object
+
+ Note: The memory allocation systems of libpq and XEmacs are
+ different. The XEmacs representation of a query result object
+ will have both the XEmacs version and the libpq version freed at
+ the next garbage collection when the object is no longer being
+ referenced. Calling this function does not release the XEmacs
+ object, it is still subject to the usual rules for Lisp objects.
+ The printed representation of the XEmacs object will contain the
+ string "DEAD" after this routine is called indicating that it is no
+ longer useful for anything.
+
+ - Function: pq-conn-defaults
+ Return a data structure that represents the connection defaults.
+ The data is returned as a list of lists, where each sublist
+ contains info regarding a single option.
\1f
-File: lispref.info, Node: CCL Statements, Next: CCL Expressions, Prev: CCL Syntax, Up: CCL
+File: lispref.info, Node: Unimplemented libpq Functions, Prev: Other libpq Functions, Up: XEmacs PostgreSQL libpq API
-CCL Statements
---------------
+Unimplemented libpq Functions
+-----------------------------
- The Emacs Code Conversion Language provides the following statement
-types: "set", "if", "branch", "loop", "repeat", "break", "read",
-"write", "call", and "end".
-
-Set statement:
-==============
-
- The "set" statement has three variants with the syntaxes `(REG =
-EXPRESSION)', `(REG ASSIGNMENT_OPERATOR EXPRESSION)', and `INTEGER'.
-The assignment operator variation of the "set" statement works the same
-way as the corresponding C expression statement does. The assignment
-operators are `+=', `-=', `*=', `/=', `%=', `&=', `|=', `^=', `<<=',
-and `>>=', and they have the same meanings as in C. A "naked integer"
-INTEGER is equivalent to a SET statement of the form `(r0 = INTEGER)'.
-
-I/O statements:
-===============
-
- The "read" statement takes one or more registers as arguments. It
-reads one byte (a C char) from the input into each register in turn.
-
- The "write" takes several forms. In the form `(write REG ...)' it
-takes one or more registers as arguments and writes each in turn to the
-output. The integer in a register (interpreted as an Emchar) is
-encoded to multibyte form (ie, Bufbytes) and written to the current
-output buffer. If it is less than 256, it is written as is. The forms
-`(write EXPRESSION)' and `(write INTEGER)' are treated analogously.
-The form `(write STRING)' writes the constant string to the output. A
-"naked string" `STRING' is equivalent to the statement `(write
-STRING)'. The form `(write REG ARRAY)' writes the REGth element of the
-ARRAY to the output.
-
-Conditional statements:
-=======================
-
- The "if" statement takes an EXPRESSION, a CCL BLOCK, and an optional
-SECOND CCL BLOCK as arguments. If the EXPRESSION evaluates to
-non-zero, the first CCL BLOCK is executed. Otherwise, if there is a
-SECOND CCL BLOCK, it is executed.
-
- The "read-if" variant of the "if" statement takes an EXPRESSION, a
-CCL BLOCK, and an optional SECOND CCL BLOCK as arguments. The
-EXPRESSION must have the form `(REG OPERATOR OPERAND)' (where OPERAND is
-a register or an integer). The `read-if' statement first reads from
-the input into the first register operand in the EXPRESSION, then
-conditionally executes a CCL block just as the `if' statement does.
-
- The "branch" statement takes an EXPRESSION and one or more CCL
-blocks as arguments. The CCL blocks are treated as a zero-indexed
-array, and the `branch' statement uses the EXPRESSION as the index of
-the CCL block to execute. Null CCL blocks may be used as no-ops,
-continuing execution with the statement following the `branch'
-statement in the containing CCL block. Out-of-range values for the
-EXPRESSION are also treated as no-ops.
-
- The "read-branch" variant of the "branch" statement takes an
-REGISTER, a CCL BLOCK, and an optional SECOND CCL BLOCK as arguments.
-The `read-branch' statement first reads from the input into the
-REGISTER, then conditionally executes a CCL block just as the `branch'
-statement does.
-
-Loop control statements:
-========================
-
- The "loop" statement creates a block with an implied jump from the
-end of the block back to its head. The loop is exited on a `break'
-statement, and continued without executing the tail by a `repeat'
-statement.
-
- The "break" statement, written `(break)', terminates the current
-loop and continues with the next statement in the current block.
-
- The "repeat" statement has three variants, `repeat', `write-repeat',
-and `write-read-repeat'. Each continues the current loop from its
-head, possibly after performing I/O. `repeat' takes no arguments and
-does no I/O before jumping. `write-repeat' takes a single argument (a
-register, an integer, or a string), writes it to the output, then jumps.
-`write-read-repeat' takes one or two arguments. The first must be a
-register. The second may be an integer or an array; if absent, it is
-implicitly set to the first (register) argument. `write-read-repeat'
-writes its second argument to the output, then reads from the input
-into the register, and finally jumps. See the `write' and `read'
-statements for the semantics of the I/O operations for each type of
-argument.
-
-Other control statements:
-=========================
-
- The "call" statement, written `(call CCL-PROGRAM-NAME)', executes a
-CCL program as a subroutine. It does not return a value to the caller,
-but can modify the register status.
-
- The "end" statement, written `(end)', terminates the CCL program
-successfully, and returns to caller (which may be a CCL program). It
-does not alter the status of the registers.
+ - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char
+ *pgport, char *pgoptions, char *pgtty, char *dbName, char
+ *login, char *pwd)
+ Synchronous database connection. PGHOST is the hostname of the
+ PostgreSQL backend to connect to. PGPORT is the TCP port number
+ to use. PGOPTIONS specifies other backend options. PGTTY
+ specifies the debugging tty to use. DBNAME specifies the database
+ name to use. LOGIN specifies the database user name. PWD
+ specifies the database user's password.
+
+ This routine is deprecated as of libpq-7.0, and its functionality
+ can be replaced by external Lisp code if needed.
+
+ - Unimplemented Function: PGconn *PQsetdb (char *pghost, char *pgport,
+ char *pgoptions, char *pgtty, char *dbName)
+ Synchronous database connection. PGHOST is the hostname of the
+ PostgreSQL backend to connect to. PGPORT is the TCP port number
+ to use. PGOPTIONS specifies other backend options. PGTTY
+ specifies the debugging tty to use. DBNAME specifies the database
+ name to use.
+
+ This routine was deprecated in libpq-6.5.
+
+ - Unimplemented Function: int PQsocket (PGconn *conn)
+ Return socket file descriptor to a backend database process. CONN
+ database connection object.
+
+ - Unimplemented Function: void PQprint (FILE *fout, PGresult *res,
+ PGprintOpt *ps)
+ Print out the results of a query to a designated C stream. FOUT C
+ stream to print to RES the query result object to print PS the
+ print options structure.
+
+ This routine is deprecated as of libpq-7.0 and cannot be sensibly
+ exported to XEmacs Lisp.
+
+ - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE
+ *fp, int fillAlign, char *fieldSep, int printHeader, int
+ quiet)
+ RES query result object to print FP C stream to print to FILLALIGN
+ pad the fields with spaces FIELDSEP field separator PRINTHEADER
+ display headers? QUIET
+
+ This routine was deprecated in libpq-6.5.
+
+ - Unimplemented Function: void PQprintTuples (PGresult *res, FILE
+ *fout, int printAttName, int terseOutput, int width)
+ RES query result object to print FOUT C stream to print to
+ PRINTATTNAME print attribute names TERSEOUTPUT delimiter bars
+ WIDTH width of column, if 0, use variable width
+
+ This routine was deprecated in libpq-6.5.
+
+ - Unimplemented Function: int PQmblen (char *s, int encoding)
+ Determine length of a multibyte encoded char at `*s'. S encoded
+ string ENCODING type of encoding
+
+ Compatibility note: This function was introduced in libpq-7.0.
+
+ - Unimplemented Function: void PQtrace (PGconn *conn, FILE *debug_port)
+ Enable tracing on `debug_port'. CONN database connection object.
+ DEBUG_PORT C output stream to use.
+
+ - Unimplemented Function: void PQuntrace (PGconn *conn)
+ Disable tracing. CONN database connection object.
+
+ - Unimplemented Function: char *PQoidStatus (PGconn *conn)
+ Return the object id as a string of the last tuple inserted. CONN
+ database connection object.
+
+ Compatibility note: This function is deprecated in libpq-7.0,
+ however it is used internally by the XEmacs binding code when
+ linked against versions prior to 7.0.
+
+ - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int
+ *result_buf, int *result_len, int result_is_int, PQArgBlock
+ *args, int nargs)
+ "Fast path" interface -- not really recommended for application use
+ CONN A database connection object. FNID RESULT_BUF RESULT_LEN
+ RESULT_IS_INT ARGS NARGS
+
+ The following set of very low level large object functions aren't
+appropriate to be exported to Lisp.
+
+ - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid,
+ int mode)
+ CONN a database connection object. LOBJID a large object ID.
+ MODE opening modes.
+
+ - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd)
+ CONN a database connection object. FD a large object file
+ descriptor
+
+ - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char
+ *buf, int len)
+ CONN a database connection object. FD a large object file
+ descriptor. BUF buffer to read into. LEN size of buffer.
+
+ - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char
+ *buf, size_t len)
+ CONN a database connection object. FD a large object file
+ descriptor. BUF buffer to write from. LEN size of buffer.
+
+ - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int
+ offset, int whence)
+ CONN a database connection object. FD a large object file
+ descriptor. OFFSET WHENCE
-\1f
-File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL
-
-CCL Expressions
----------------
-
- CCL, unlike Lisp, uses infix expressions. The simplest CCL
-expressions consist of a single OPERAND, either a register (one of `r0',
-..., `r0') or an integer. Complex expressions are lists of the form `(
-EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not
-expressions.
-
- In the following table, X is the target resister for a "set". In
-subexpressions, this is implicitly `r7'. This means that `>8', `//',
-`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since
-they return parts of their values in `r7'. Y may be an expression,
-register, or integer, while Z must be a register or an integer.
-
-Name Operator Code C-like Description
-CCL_PLUS `+' 0x00 X = Y + Z
-CCL_MINUS `-' 0x01 X = Y - Z
-CCL_MUL `*' 0x02 X = Y * Z
-CCL_DIV `/' 0x03 X = Y / Z
-CCL_MOD `%' 0x04 X = Y % Z
-CCL_AND `&' 0x05 X = Y & Z
-CCL_OR `|' 0x06 X = Y | Z
-CCL_XOR `^' 0x07 X = Y ^ Z
-CCL_LSH `<<' 0x08 X = Y << Z
-CCL_RSH `>>' 0x09 X = Y >> Z
-CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z
-CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF
-CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z
-CCL_LS `<' 0x10 X = (X < Y)
-CCL_GT `>' 0x11 X = (X > Y)
-CCL_EQ `==' 0x12 X = (X == Y)
-CCL_LE `<=' 0x13 X = (X <= Y)
-CCL_GE `>=' 0x14 X = (X >= Y)
-CCL_NE `!=' 0x15 X = (X != Y)
-CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z))
- r[7] = LOWER_BYTE (SJIS (Y, Z)
-CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z))
- r[7] = LOWER_BYTE (DE-SJIS (Y, Z))
-
- The CCL operators are as in C, with the addition of CCL_LSH8,
-CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The
-CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes
-as the high and low bytes of a two-byte character code. (SJIS stands
-for Shift JIS, an encoding of Japanese characters used by Microsoft.
-CCL_ENCODE_SJIS is a complicated transformation of the Japanese
-standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.)
-It is somewhat odd to represent the SJIS operations in infix form.
+ - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode)
+ CONN a database connection object. MODE opening modes.
+
+ - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd)
+ CONN a database connection object. FD a large object file
+ descriptor.
+
+ - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid)
+ CONN a database connection object. LBOJID a large object ID.
\1f
-File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL
-
-Calling CCL
------------
-
- CCL programs are called automatically during Emacs buffer I/O when
-the external representation has a coding system type of `shift-jis',
-`big5', or `ccl'. The program is specified by the coding system (*note
-Coding Systems::). You can also call CCL programs from other CCL
-programs, and from Lisp using these functions:
-
- - Function: ccl-execute ccl-program status
- Execute CCL-PROGRAM with registers initialized by STATUS.
- CCL-PROGRAM is a vector of compiled CCL code created by
- `ccl-compile'. It is an error for the program to try to execute a
- CCL I/O command. STATUS must be a vector of nine values,
- specifying the initial value for the R0, R1 .. R7 registers and
- for the instruction counter IC. A `nil' value for a register
- initializer causes the register to be set to 0. A `nil' value for
- the IC initializer causes execution to start at the beginning of
- the program. When the program is done, STATUS is modified (by
- side-effect) to contain the ending values for the corresponding
- registers and IC.
-
- - Function: ccl-execute-on-string ccl-program status str &optional
- continue
- Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is
- a vector of compiled CCL code created by `ccl-compile'. STATUS
- must be a vector of nine values, specifying the initial value for
- the R0, R1 .. R7 registers and for the instruction counter IC. A
- `nil' value for a register initializer causes the register to be
- set to 0. A `nil' value for the IC initializer causes execution
- to start at the beginning of the program. An optional fourth
- argument CONTINUE, if non-nil, causes the IC to remain on the
- unsatisfied read operation if the program terminates due to
- exhaustion of the input buffer. Otherwise the IC is set to the end
- of the program. When the program is done, STATUS is modified (by
- side-effect) to contain the ending values for the corresponding
- registers and IC. Returns the resulting string.
-
- To call a CCL program from another CCL program, it must first be
-registered:
-
- - Function: register-ccl-program name ccl-program
- Register NAME for CCL program PROGRAM in `ccl-program-table'.
- PROGRAM should be the compiled form of a CCL program, or nil.
- Return index number of the registered CCL program.
-
- Information about the processor time used by the CCL interpreter can
-be obtained using these functions:
-
- - Function: ccl-elapsed-time
- Returns the elapsed processor time of the CCL interpreter as cons
- of user and system time, as floating point numbers measured in
- seconds. If only one overall value can be determined, the return
- value will be a cons of that value and 0.
-
- - Function: ccl-reset-elapsed-time
- Resets the CCL interpreter's internal elapsed time registers.
+File: lispref.info, Node: XEmacs PostgreSQL libpq Examples, Prev: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support
+
+XEmacs PostgreSQL libpq Examples
+================================
+
+ This is an example of one method of establishing an asynchronous
+connection.
+
+ (defun database-poller (P)
+ (message "%S before poll" (pq-pgconn P 'pq::status))
+ (pq-connect-poll P)
+ (message "%S after poll" (pq-pgconn P 'pq::status))
+ (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
+ (message "Done!")
+ (add-timeout .1 'database-poller P)))
+ => database-poller
+ (progn
+ (setq P (pq-connect-start ""))
+ (add-timeout .1 'database-poller P))
+ => pg::connection-started before poll
+ => pg::connection-made after poll
+ => pg::connection-made before poll
+ => pg::connection-awaiting-response after poll
+ => pg::connection-awaiting-response before poll
+ => pg::connection-auth-ok after poll
+ => pg::connection-auth-ok before poll
+ => pg::connection-setenv after poll
+ => pg::connection-setenv before poll
+ => pg::connection-ok after poll
+ => Done!
+ P
+ => #<PGconn localhost:25432 steve/steve>
+
+ Here is an example of one method of doing an asynchronous reset.
+
+ (defun database-poller (P)
+ (let (PS)
+ (message "%S before poll" (pq-pgconn P 'pq::status))
+ (setq PS (pq-reset-poll P))
+ (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS)
+ (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
+ (message "Done!")
+ (add-timeout .1 'database-poller P))))
+ => database-poller
+ (progn
+ (pq-reset-start P)
+ (add-timeout .1 'database-poller P))
+ => pg::connection-started before poll
+ => pg::connection-made after poll [pgres::polling-writing]
+ => pg::connection-made before poll
+ => pg::connection-awaiting-response after poll [pgres::polling-reading]
+ => pg::connection-awaiting-response before poll
+ => pg::connection-setenv after poll [pgres::polling-reading]
+ => pg::connection-setenv before poll
+ => pg::connection-ok after poll [pgres::polling-ok]
+ => Done!
+ P
+ => #<PGconn localhost:25432 steve/steve>
+
+ And finally, an asynchronous query.
+
+ (defun database-poller (P)
+ (let (R)
+ (pq-consume-input P)
+ (if (pq-is-busy P)
+ (add-timeout .1 'database-poller P)
+ (setq R (pq-get-result P))
+ (if R
+ (progn
+ (push R result-list)
+ (add-timeout .1 'database-poller P))))))
+ => database-poller
+ (when (pq-send-query P "SELECT * FROM xemacs_test;")
+ (setq result-list nil)
+ (add-timeout .1 'database-poller P))
+ => 885
+ ;; wait a moment
+ result-list
+ => (#<PGresult PGRES_TUPLES_OK - SELECT>)
+
+ Here is an example showing how multiple SQL statements in a single
+query can have all their results collected.
+ ;; Using the same `database-poller' function from the previous example
+ (when (pq-send-query P "SELECT * FROM xemacs_test;
+ SELECT * FROM pg_database;
+ SELECT * FROM pg_user;")
+ (setq result-list nil)
+ (add-timeout .1 'database-poller P))
+ => 1782
+ ;; wait a moment
+ result-list
+ => (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
+
+ Here is an example which illustrates collecting all data from a
+query, including the field names.
+
+ (defun pg-util-query-results (results)
+ "Retrieve results of last SQL query into a list structure."
+ (let ((i (1- (pq-ntuples R)))
+ j l1 l2)
+ (while (>= i 0)
+ (setq j (1- (pq-nfields R)))
+ (setq l2 nil)
+ (while (>= j 0)
+ (push (pq-get-value R i j) l2)
+ (decf j))
+ (push l2 l1)
+ (decf i))
+ (setq j (1- (pq-nfields R)))
+ (setq l2 nil)
+ (while (>= j 0)
+ (push (pq-fname R j) l2)
+ (decf j))
+ (push l2 l1)
+ l1))
+ => pg-util-query-results
+ (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;"))
+ => #<PGresult PGRES_TUPLES_OK - SELECT>
+ (pg-util-query-results R)
+ => (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1"))
+
+ Here is an example of a query that uses a database cursor.
+
+ (let (data R)
+ (setq R (pq-exec P "BEGIN;"))
+ (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;"))
+
+ (setq R (pq-exec P "FETCH k_cursor;"))
+ (while (eq (pq-ntuples R) 1)
+ (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data)
+ (setq R (pq-exec P "FETCH k_cursor;")))
+ (setq R (pq-exec P "END;"))
+ data)
+ => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1"))
+
+ Here's another example of cursors, this time with a Lisp macro to
+implement a mapping function over a table.
+
+ (defmacro map-db (P table condition callout)
+ `(let (R)
+ (pq-exec ,P "BEGIN;")
+ (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM "
+ ,table
+ " "
+ ,condition
+ " ORDER BY f1 DESC;"))
+ (setq R (pq-exec P "FETCH k_cursor;"))
+ (while (eq (pq-ntuples R) 1)
+ (,callout (pq-get-value R 0 0) (pq-get-value R 0 1))
+ (setq R (pq-exec P "FETCH k_cursor;")))
+ (pq-exec P "END;")))
+ => map-db
+ (defun callback (arg1 arg2)
+ (message "arg1 = %s, arg2 = %s" arg1 arg2))
+ => callback
+ (map-db P "xemacs_test" "WHERE field2 > 10" callback)
+ => arg1 = stuff, arg2 = 42
+ => arg1 = b, arg2 = 97
+ => arg1 = a string, arg2 = 12
+ => arg1 = a, arg2 = 97
+ => #<PGresult PGRES_COMMAND_OK - COMMIT>
\1f
-File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL
+File: lispref.info, Node: Internationalization, Next: MULE, Prev: PostgreSQL Support, Up: Top
-CCL Examples
-------------
+Internationalization
+********************
- This section is not yet written.
+* Menu:
-\1f
-File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE
-
-Category Tables
-===============
-
- A category table is a type of char table used for keeping track of
-categories. Categories are used for classifying characters for use in
-regexps--you can refer to a category rather than having to use a
-complicated [] expression (and category lookups are significantly
-faster).
-
- There are 95 different categories available, one for each printable
-character (including space) in the ASCII charset. Each category is
-designated by one such character, called a "category designator". They
-are specified in a regexp using the syntax `\cX', where X is a category
-designator. (This is not yet implemented.)
-
- A category table specifies, for each character, the categories that
-the character is in. Note that a character can be in more than one
-category. More specifically, a category table maps from a character to
-either the value `nil' (meaning the character is in no categories) or a
-95-element bit vector, specifying for each of the 95 categories whether
-the character is in that category.
-
- Special Lisp functions are provided that abstract this, so you do not
-have to directly manipulate bit vectors.
-
- - Function: category-table-p obj
- This function returns `t' if ARG is a category table.
-
- - Function: category-table &optional buffer
- This function returns the current category table. This is the one
- specified by the current buffer, or by BUFFER if it is non-`nil'.
-
- - Function: standard-category-table
- This function returns the standard category table. This is the
- one used for new buffers.
-
- - Function: copy-category-table &optional table
- This function constructs a new category table and return it. It
- is a copy of the TABLE, which defaults to the standard category
- table.
-
- - Function: set-category-table table &optional buffer
- This function selects a new category table for BUFFER. One
- argument, a category table. BUFFER defaults to the current buffer
- if omitted.
-
- - Function: category-designator-p obj
- This function returns `t' if ARG is a category designator (a char
- in the range `' '' to `'~'').
-
- - Function: category-table-value-p obj
- This function returns `t' if ARG is a category table value. Valid
- values are `nil' or a bit vector of size 95.
+* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
+* I18N Level 3:: Support for localized messages.
+* I18N Level 4:: Support for Asian languages.
\1f
-File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top
+File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
+
+I18N Levels 1 and 2
+===================
-Tips and Standards
-******************
+ XEmacs is now compliant with I18N levels 1 and 2. Specifically,
+this means that it is 8-bit clean and correctly handles time and date
+functions. XEmacs will correctly display the entire ISO-Latin 1
+character set.
- This chapter describes no additional features of XEmacs Lisp.
-Instead it gives advice on making effective use of the features
-described in the previous chapters.
+ The compose key may now be used to create any character in the
+ISO-Latin 1 character set not directly available via the keyboard.. In
+order for the compose key to work it is necessary to load the file
+`x-compose.el'. At any time while composing a character, `C-h' will
+display all valid completions and the character which would be produced.
+
+\1f
+File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
+
+I18N Level 3
+============
* Menu:
-* Style Tips:: Writing clean and robust programs.
-* Compilation Tips:: Making compiled code run fast.
-* Documentation Tips:: Writing readable documentation strings.
-* Comment Tips:: Conventions for writing comments.
-* Library Headers:: Standard headers for library packages.
+* Level 3 Basics::
+* Level 3 Primitives::
+* Dynamic Messaging::
+* Domain Specification::
+* Documentation String Extraction::
\1f
-File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips
+File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
-Writing Clean Lisp Programs
-===========================
+Level 3 Basics
+--------------
- Here are some tips for avoiding common errors in writing Lisp code
-intended for widespread use:
-
- * Since all global variables share the same name space, and all
- functions share another name space, you should choose a short word
- to distinguish your program from other Lisp programs. Then take
- care to begin the names of all global variables, constants, and
- functions with the chosen prefix. This helps avoid name conflicts.
-
- This recommendation applies even to names for traditional Lisp
- primitives that are not primitives in XEmacs Lisp--even to `cadr'.
- Believe it or not, there is more than one plausible way to define
- `cadr'. Play it safe; append your name prefix to produce a name
- like `foo-cadr' or `mylib-cadr' instead.
-
- If you write a function that you think ought to be added to Emacs
- under a certain name, such as `twiddle-files', don't call it by
- that name in your program. Call it `mylib-twiddle-files' in your
- program, and send mail to `bug-gnu-emacs@prep.ai.mit.edu'
- suggesting we add it to Emacs. If and when we do, we can change
- the name easily enough.
-
- If one prefix is insufficient, your package may use two or three
- alternative common prefixes, so long as they make sense.
-
- Separate the prefix from the rest of the symbol name with a hyphen,
- `-'. This will be consistent with XEmacs itself and with most
- Emacs Lisp programs.
-
- * It is often useful to put a call to `provide' in each separate
- library program, at least if there is more than one entry point to
- the program.
-
- * If a file requires certain other library programs to be loaded
- beforehand, then the comments at the beginning of the file should
- say so. Also, use `require' to make sure they are loaded.
-
- * If one file FOO uses a macro defined in another file BAR, FOO
- should contain this expression before the first use of the macro:
-
- (eval-when-compile (require 'BAR))
-
- (And BAR should contain `(provide 'BAR)', to make the `require'
- work.) This will cause BAR to be loaded when you byte-compile
- FOO. Otherwise, you risk compiling FOO without the necessary
- macro loaded, and that would produce compiled code that won't work
- right. *Note Compiling Macros::.
-
- Using `eval-when-compile' avoids loading BAR when the compiled
- version of FOO is _used_.
-
- * If you define a major mode, make sure to run a hook variable using
- `run-hooks', just as the existing major modes do. *Note Hooks::.
-
- * If the purpose of a function is to tell you whether a certain
- condition is true or false, give the function a name that ends in
- `p'. If the name is one word, add just `p'; if the name is
- multiple words, add `-p'. Examples are `framep' and
- `frame-live-p'.
-
- * If a user option variable records a true-or-false condition, give
- it a name that ends in `-flag'.
-
- * Please do not define `C-c LETTER' as a key in your major modes.
- These sequences are reserved for users; they are the *only*
- sequences reserved for users, so we cannot do without them.
-
- Instead, define sequences consisting of `C-c' followed by a
- non-letter. These sequences are reserved for major modes.
+ XEmacs now provides alpha-level functionality for I18N Level 3.
+This means that everything necessary for full messaging is available,
+but not every file has been converted.
- Changing all the major modes in Emacs 18 so they would follow this
- convention was a lot of work. Abandoning this convention would
- make that work go to waste, and inconvenience users.
+ The two message files which have been created are `src/emacs.po' and
+`lisp/packages/mh-e.po'. Both files need to be converted using
+`msgfmt', and the resulting `.mo' files placed in some locale's
+`LC_MESSAGES' directory. The test "translations" in these files are
+the original messages prefixed by `TRNSLT_'.
- * Sequences consisting of `C-c' followed by `{', `}', `<', `>', `:'
- or `;' are also reserved for major modes.
-
- * Sequences consisting of `C-c' followed by any other punctuation
- character are allocated for minor modes. Using them in a major
- mode is not absolutely prohibited, but if you do that, the major
- mode binding may be shadowed from time to time by minor modes.
-
- * You should not bind `C-h' following any prefix character (including
- `C-c'). If you don't bind `C-h', it is automatically available as
- a help character for listing the subcommands of the prefix
- character.
-
- * You should not bind a key sequence ending in <ESC> except following
- another <ESC>. (That is, it is ok to bind a sequence ending in
- `<ESC> <ESC>'.)
-
- The reason for this rule is that a non-prefix binding for <ESC> in
- any context prevents recognition of escape sequences as function
- keys in that context.
-
- * Applications should not bind mouse events based on button 1 with
- the shift key held down. These events include `S-mouse-1',
- `M-S-mouse-1', `C-S-mouse-1', and so on. They are reserved for
- users.
-
- * Modes should redefine `mouse-2' as a command to follow some sort of
- reference in the text of a buffer, if users usually would not want
- to alter the text in that buffer by hand. Modes such as Dired,
- Info, Compilation, and Occur redefine it in this way.
-
- * When a package provides a modification of ordinary Emacs behavior,
- it is good to include a command to enable and disable the feature,
- Provide a command named `WHATEVER-mode' which turns the feature on
- or off, and make it autoload (*note Autoload::). Design the
- package so that simply loading it has no visible effect--that
- should not enable the feature. Users will request the feature by
- invoking the command.
-
- * It is a bad idea to define aliases for the Emacs primitives. Use
- the standard names instead.
-
- * Redefining an Emacs primitive is an even worse idea. It may do
- the right thing for a particular program, but there is no telling
- what other programs might break as a result.
-
- * If a file does replace any of the functions or library programs of
- standard XEmacs, prominent comments at the beginning of the file
- should say which functions are replaced, and how the behavior of
- the replacements differs from that of the originals.
-
- * Please keep the names of your XEmacs Lisp source files to 13
- characters or less. This way, if the files are compiled, the
- compiled files' names will be 14 characters or less, which is
- short enough to fit on all kinds of Unix systems.
-
- * Don't use `next-line' or `previous-line' in programs; nearly
- always, `forward-line' is more convenient as well as more
- predictable and robust. *Note Text Lines::.
-
- * Don't call functions that set the mark, unless setting the mark is
- one of the intended features of your program. The mark is a
- user-level feature, so it is incorrect to change the mark except
- to supply a value for the user's benefit. *Note The Mark::.
-
- In particular, don't use these functions:
-
- * `beginning-of-buffer', `end-of-buffer'
-
- * `replace-string', `replace-regexp'
-
- If you just want to move point, or replace a certain string,
- without any of the other features intended for interactive users,
- you can replace these functions with one or two lines of simple
- Lisp code.
-
- * Use lists rather than vectors, except when there is a particular
- reason to use a vector. Lisp has more facilities for manipulating
- lists than for vectors, and working with lists is usually more
- convenient.
-
- Vectors are advantageous for tables that are substantial in size
- and are accessed in random order (not searched front to back),
- provided there is no need to insert or delete elements (only lists
- allow that).
-
- * The recommended way to print a message in the echo area is with
- the `message' function, not `princ'. *Note The Echo Area::.
-
- * When you encounter an error condition, call the function `error'
- (or `signal'). The function `error' does not return. *Note
- Signaling Errors::.
-
- Do not use `message', `throw', `sleep-for', or `beep' to report
- errors.
-
- * An error message should start with a capital letter but should not
- end with a period.
-
- * Try to avoid using recursive edits. Instead, do what the Rmail `e'
- command does: use a new local keymap that contains one command
- defined to switch back to the old local keymap. Or do what the
- `edit-options' command does: switch to another buffer and let the
- user switch back at will. *Note Recursive Editing::.
-
- * In some other systems there is a convention of choosing variable
- names that begin and end with `*'. We don't use that convention
- in Emacs Lisp, so please don't use it in your programs. (Emacs
- uses such names only for program-generated buffers.) The users
- will find Emacs more coherent if all libraries use the same
- conventions.
-
- * Indent each function with `C-M-q' (`indent-sexp') using the
- default indentation parameters.
-
- * Don't make a habit of putting close-parentheses on lines by
- themselves; Lisp programmers find this disconcerting. Once in a
- while, when there is a sequence of many consecutive
- close-parentheses, it may make sense to split them in one or two
- significant places.
-
- * Please put a copyright notice on the file if you give copies to
- anyone. Use the same lines that appear at the top of the Lisp
- files in XEmacs itself. If you have not signed papers to assign
- the copyright to the Foundation, then place your name in the
- copyright notice in place of the Foundation's name.
+ The domain for a variable is stored on the variable's property list
+under the property name VARIABLE-DOMAIN. The function
+`documentation-property' uses this information when translating a
+variable's documentation.
\1f
-File: lispref.info, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips
-
-Tips for Making Compiled Code Fast
-==================================
-
- Here are ways of improving the execution speed of byte-compiled Lisp
-programs.
-
- * Use the `profile' library to profile your program. See the file
- `profile.el' for instructions.
-
- * Use iteration rather than recursion whenever possible. Function
- calls are slow in XEmacs Lisp even when a compiled function is
- calling another compiled function.
-
- * Using the primitive list-searching functions `memq', `member',
- `assq', or `assoc' is even faster than explicit iteration. It may
- be worth rearranging a data structure so that one of these
- primitive search functions can be used.
-
- * Certain built-in functions are handled specially in byte-compiled
- code, avoiding the need for an ordinary function call. It is a
- good idea to use these functions rather than alternatives. To see
- whether a function is handled specially by the compiler, examine
- its `byte-compile' property. If the property is non-`nil', then
- the function is handled specially.
-
- For example, the following input will show you that `aref' is
- compiled specially (*note Array Functions::) while `elt' is not
- (*note Sequence Functions::):
-
- (get 'aref 'byte-compile)
- => byte-compile-two-args
-
- (get 'elt 'byte-compile)
- => nil
-
- * If calling a small function accounts for a substantial part of
- your program's running time, make the function inline. This
- eliminates the function call overhead. Since making a function
- inline reduces the flexibility of changing the program, don't do
- it unless it gives a noticeable speedup in something slow enough
- that users care about the speed. *Note Inline Functions::.
+File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3
-\1f
-File: lispref.info, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips
-
-Tips for Documentation Strings
-==============================
-
- Here are some tips for the writing of documentation strings.
-
- * Every command, function, or variable intended for users to know
- about should have a documentation string.
-
- * An internal variable or subroutine of a Lisp program might as well
- have a documentation string. In earlier Emacs versions, you could
- save space by using a comment instead of a documentation string,
- but that is no longer the case.
-
- * The first line of the documentation string should consist of one
- or two complete sentences that stand on their own as a summary.
- `M-x apropos' displays just the first line, and if it doesn't
- stand on its own, the result looks bad. In particular, start the
- first line with a capital letter and end with a period.
-
- The documentation string can have additional lines that expand on
- the details of how to use the function or variable. The
- additional lines should be made up of complete sentences also, but
- they may be filled if that looks good.
-
- * For consistency, phrase the verb in the first sentence of a
- documentation string as an infinitive with "to" omitted. For
- instance, use "Return the cons of A and B." in preference to
- "Returns the cons of A and B." Usually it looks good to do
- likewise for the rest of the first paragraph. Subsequent
- paragraphs usually look better if they have proper subjects.
-
- * Write documentation strings in the active voice, not the passive,
- and in the present tense, not the future. For instance, use
- "Return a list containing A and B." instead of "A list containing
- A and B will be returned."
-
- * Avoid using the word "cause" (or its equivalents) unnecessarily.
- Instead of, "Cause Emacs to display text in boldface," write just
- "Display text in boldface."
-
- * Do not start or end a documentation string with whitespace.
-
- * Format the documentation string so that it fits in an Emacs window
- on an 80-column screen. It is a good idea for most lines to be no
- wider than 60 characters. The first line can be wider if
- necessary to fit the information that ought to be there.
-
- However, rather than simply filling the entire documentation
- string, you can make it much more readable by choosing line breaks
- with care. Use blank lines between topics if the documentation
- string is long.
-
- * *Do not* indent subsequent lines of a documentation string so that
- the text is lined up in the source code with the text of the first
- line. This looks nice in the source code, but looks bizarre when
- users view the documentation. Remember that the indentation
- before the starting double-quote is not part of the string!
-
- * A variable's documentation string should start with `*' if the
- variable is one that users would often want to set interactively.
- If the value is a long list, or a function, or if the variable
- would be set only in init files, then don't start the
- documentation string with `*'. *Note Defining Variables::.
-
- * The documentation string for a variable that is a yes-or-no flag
- should start with words such as "Non-nil means...", to make it
- clear that all non-`nil' values are equivalent and indicate
- explicitly what `nil' and non-`nil' mean.
-
- * When a function's documentation string mentions the value of an
- argument of the function, use the argument name in capital letters
- as if it were a name for that value. Thus, the documentation
- string of the function `/' refers to its second argument as
- `DIVISOR', because the actual argument name is `divisor'.
-
- Also use all caps for meta-syntactic variables, such as when you
- show the decomposition of a list or vector into subunits, some of
- which may vary.
-
- * When a documentation string refers to a Lisp symbol, write it as it
- would be printed (which usually means in lower case), with
- single-quotes around it. For example: `lambda'. There are two
- exceptions: write t and nil without single-quotes. (In this
- manual, we normally do use single-quotes for those symbols.)
-
- * Don't write key sequences directly in documentation strings.
- Instead, use the `\\[...]' construct to stand for them. For
- example, instead of writing `C-f', write `\\[forward-char]'. When
- Emacs displays the documentation string, it substitutes whatever
- key is currently bound to `forward-char'. (This is normally `C-f',
- but it may be some other character if the user has moved key
- bindings.) *Note Keys in Documentation::.
-
- * In documentation strings for a major mode, you will want to refer
- to the key bindings of that mode's local map, rather than global
- ones. Therefore, use the construct `\\<...>' once in the
- documentation string to specify which key map to use. Do this
- before the first use of `\\[...]'. The text inside the `\\<...>'
- should be the name of the variable containing the local keymap for
- the major mode.
-
- It is not practical to use `\\[...]' very many times, because
- display of the documentation string will become slow. So use this
- to describe the most important commands in your major mode, and
- then use `\\{...}' to display the rest of the mode's keymap.
+Level 3 Primitives
+------------------
+
+ - Function: gettext string
+ This function looks up STRING in the default message domain and
+ returns its translation. If `I18N3' was not enabled when XEmacs
+ was compiled, it just returns STRING.
+
+ - Function: dgettext domain string
+ This function looks up STRING in the specified message domain and
+ returns its translation. If `I18N3' was not enabled when XEmacs
+ was compiled, it just returns STRING.
+
+ - Function: bind-text-domain domain pathname
+ This function associates a pathname with a message domain. Here's
+ how the path to message file is constructed under SunOS 5.x:
+
+ `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
+
+ If `I18N3' was not enabled when XEmacs was compiled, this function
+ does nothing.
+
+ - Special Form: domain string
+ This function specifies the text domain used for translating
+ documentation strings and interactive prompts of a function. For
+ example, write:
+
+ (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
+
+ to specify `emacs-foo' as the text domain of the function `foo'.
+ The "call" to `domain' is actually a declaration rather than a
+ function; when actually called, `domain' just returns `nil'.
+
+ - Function: domain-of function
+ This function returns the text domain of FUNCTION; it returns
+ `nil' if it is the default domain. If `I18N3' was not enabled
+ when XEmacs was compiled, it always returns `nil'.
\1f
-File: lispref.info, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips
-
-Tips on Writing Comments
-========================
-
- We recommend these conventions for where to put comments and how to
-indent them:
-
-`;'
- Comments that start with a single semicolon, `;', should all be
- aligned to the same column on the right of the source code. Such
- comments usually explain how the code on the same line does its
- job. In Lisp mode and related modes, the `M-;'
- (`indent-for-comment') command automatically inserts such a `;' in
- the right place, or aligns such a comment if it is already present.
-
- This and following examples are taken from the Emacs sources.
-
- (setq base-version-list ; there was a base
- (assoc (substring fn 0 start-vn) ; version to which
- file-version-assoc-list)) ; this looks like
- ; a subversion
-
-`;;'
- Comments that start with two semicolons, `;;', should be aligned to
- the same level of indentation as the code. Such comments usually
- describe the purpose of the following lines or the state of the
- program at that point. For example:
-
- (prog1 (setq auto-fill-function
- ...
- ...
- ;; update modeline
- (redraw-modeline)))
-
- Every function that has no documentation string (because it is use
- only internally within the package it belongs to), should have
- instead a two-semicolon comment right before the function,
- explaining what the function does and how to call it properly.
- Explain precisely what each argument means and how the function
- interprets its possible values.
-
-`;;;'
- Comments that start with three semicolons, `;;;', should start at
- the left margin. Such comments are used outside function
- definitions to make general statements explaining the design
- principles of the program. For example:
-
- ;;; This Lisp code is run in XEmacs
- ;;; when it is to operate as a server
- ;;; for other processes.
-
- Another use for triple-semicolon comments is for commenting out
- lines within a function. We use triple-semicolons for this
- precisely so that they remain at the left margin.
-
- (defun foo (a)
- ;;; This is no longer necessary.
- ;;; (force-mode-line-update)
- (message "Finished with %s" a))
-
-`;;;;'
- Comments that start with four semicolons, `;;;;', should be aligned
- to the left margin and are used for headings of major sections of a
- program. For example:
-
- ;;;; The kill ring
-
-The indentation commands of the Lisp modes in XEmacs, such as `M-;'
-(`indent-for-comment') and <TAB> (`lisp-indent-line') automatically
-indent comments according to these conventions, depending on the number
-of semicolons. *Note Manipulating Comments: (emacs)Comments.
+File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3
+
+Dynamic Messaging
+-----------------
+
+ The `format' function has been extended to permit you to change the
+order of parameter insertion. For example, the conversion format
+`%1$s' inserts parameter one as a string, while `%2$s' inserts
+parameter two. This is useful when creating translations which require
+you to change the word order.
\1f
-File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips
+File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3
-Conventional Headers for XEmacs Libraries
-=========================================
+Domain Specification
+--------------------
- XEmacs has conventions for using special comments in Lisp libraries
-to divide them into sections and give information such as who wrote
-them. This section explains these conventions. First, an example:
+ The default message domain of XEmacs is `emacs'. For add-on
+packages, it is best to use a different domain. For example, let us
+say we want to convert the "gorilla" package to use the domain
+`emacs-gorilla'. To translate the message "What gorilla?", use
+`dgettext' as follows:
- ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
-
- ;; Copyright (C) 1992 Free Software Foundation, Inc.
-
- ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
- ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
- ;; Created: 14 Jul 1992
- ;; Version: 1.2
- ;; Keywords: docs
-
- ;; This file is part of XEmacs.
- COPYING PERMISSIONS...
+ (dgettext "emacs-gorilla" "What gorilla?")
- The very first line should have this format:
+ A function (or macro) which has a documentation string or an
+interactive prompt needs to be associated with the domain in order for
+the documentation or prompt to be translated. This is done with the
+`domain' special form as follows:
- ;;; FILENAME --- DESCRIPTION
+ (defun scratch (location)
+ "Scratch the specified location."
+ (domain "emacs-gorilla")
+ (interactive "sScratch: ")
+ ... )
-The description should be complete in one line.
+ It is most efficient to specify the domain in the first line of the
+function body, before the `interactive' form.
- After the copyright notice come several "header comment" lines, each
-beginning with `;; HEADER-NAME:'. Here is a table of the conventional
-possibilities for HEADER-NAME:
+ For variables and constants which have documentation strings,
+specify the domain after the documentation.
-`Author'
- This line states the name and net address of at least the principal
- author of the library.
+ - Special Form: defvar symbol [value [doc-string [domain]]]
+ Example:
+ (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
- If there are multiple authors, you can list them on continuation
- lines led by `;;' and a tab character, like this:
+ - Special Form: defconst symbol [value [doc-string [domain]]]
+ Example:
+ (defconst limbs 4 "Number of limbs" "emacs-gorilla")
- ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
- ;; Dave Sill <de5@ornl.gov>
- ;; Dave Brennan <brennan@hal.com>
- ;; Eric Raymond <esr@snark.thyrsus.com>
+ Autoloaded functions which are specified in `loaddefs.el' do not need
+to have a domain specification, because their documentation strings are
+extracted into the main message base. However, for autoloaded functions
+which are specified in a separate package, use following syntax:
-`Maintainer'
- This line should contain a single name/address as in the Author
- line, or an address only, or the string `FSF'. If there is no
- maintainer line, the person(s) in the Author field are presumed to
- be the maintainers. The example above is mildly bogus because the
- maintainer line is redundant.
+ - Function: autoload symbol filename &optional docstring interactive
+ macro domain
+ Example:
+ (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
- The idea behind the `Author' and `Maintainer' lines is to make
- possible a Lisp function to "send mail to the maintainer" without
- having to mine the name out by hand.
+\1f
+File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3
- Be sure to surround the network address with `<...>' if you
- include the person's full name as well as the network address.
+Documentation String Extraction
+-------------------------------
-`Created'
- This optional line gives the original creation date of the file.
- For historical interest only.
+ The utility `etc/make-po' scans the file `DOC' to extract
+documentation strings and creates a message file `doc.po'. This file
+may then be inserted within `emacs.po'.
-`Version'
- If you wish to record version numbers for the individual Lisp
- program, put them in this line.
+ Currently, `make-po' is hard-coded to read from `DOC' and write to
+`doc.po'. In order to extract documentation strings from an add-on
+package, first run `make-docfile' on the package to produce the `DOC'
+file. Then run `make-po -p' with the `-p' argument to indicate that we
+are extracting documentation for an add-on package.
-`Adapted-By'
- In this header line, place the name of the person who adapted the
- library for installation (to make it fit the style conventions, for
- example).
+ (The `-p' argument is a kludge to make up for a subtle difference
+between pre-loaded documentation and add-on documentation: For add-on
+packages, the final carriage returns in the strings produced by
+`make-docfile' must be ignored.)
-`Keywords'
- This line lists keywords for the `finder-by-keyword' help command.
- This field is important; it's how people will find your package
- when they're looking for things by topic area. To separate the
- keywords, you can use spaces, commas, or both.
+\1f
+File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization
- Just about every Lisp library ought to have the `Author' and
-`Keywords' header comment lines. Use the others if they are
-appropriate. You can also put in header lines with other header
-names--they have no standard meanings, so they can't do any harm.
+I18N Level 4
+============
- We use additional stylized comments to subdivide the contents of the
-library file. Here is a table of them:
+ The Asian-language support in XEmacs is called "MULE". *Note MULE::.
-`;;; Commentary:'
- This begins introductory comments that explain how the library
- works. It should come right after the copying permissions.
+\1f
+File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top
-`;;; Change log:'
- This begins change log information stored in the library file (if
- you store the change history there). For most of the Lisp files
- distributed with XEmacs, the change history is kept in the file
- `ChangeLog' and not in the source file at all; these files do not
- have a `;;; Change log:' line.
+MULE
+****
-`;;; Code:'
- This begins the actual code of the program.
+ "MULE" is the name originally given to the version of GNU Emacs
+extended for multi-lingual (and in particular Asian-language) support.
+"MULE" is short for "MUlti-Lingual Emacs". It is an extension and
+complete rewrite of Nemacs ("Nihon Emacs" where "Nihon" is the Japanese
+word for "Japan"), which only provided support for Japanese. XEmacs
+refers to its multi-lingual support as "MULE support" since it is based
+on "MULE".
-`;;; FILENAME ends here'
- This is the "footer line"; it appears at the very end of the file.
- Its purpose is to enable people to detect truncated versions of
- the file from the lack of a footer line.
+* Menu:
+
+* Internationalization Terminology::
+ Definition of various internationalization terms.
+* Charsets:: Sets of related characters.
+* MULE Characters:: Working with characters in XEmacs/MULE.
+* Composite Characters:: Making new characters by overstriking other ones.
+* Coding Systems:: Ways of representing a string of chars using integers.
+* CCL:: A special language for writing fast converters.
+* Category Tables:: Subdividing charsets into groups.
+
+\1f
+File: lispref.info, Node: Internationalization Terminology, Next: Charsets, Up: MULE
+
+Internationalization Terminology
+================================
+
+ In internationalization terminology, a string of text is divided up
+into "characters", which are the printable units that make up the text.
+A single character is (for example) a capital `A', the number `2', a
+Katakana character, a Hangul character, a Kanji ideograph (an
+"ideograph" is a "picture" character, such as is used in Japanese
+Kanji, Chinese Hanzi, and Korean Hanja; typically there are thousands
+of such ideographs in each language), etc. The basic property of a
+character is that it is the smallest unit of text with semantic
+significance in text processing.
+
+ Human beings normally process text visually, so to a first
+approximation a character may be identified with its shape. Note that
+the same character may be drawn by two different people (or in two
+different fonts) in slightly different ways, although the "basic shape"
+will be the same. But consider the works of Scott Kim; human beings
+can recognize hugely variant shapes as the "same" character.
+Sometimes, especially where characters are extremely complicated to
+write, completely different shapes may be defined as the "same"
+character in national standards. The Taiwanese variant of Hanzi is
+generally the most complicated; over the centuries, the Japanese,
+Koreans, and the People's Republic of China have adopted
+simplifications of the shape, but the line of descent from the original
+shape is recorded, and the meanings and pronunciation of different
+forms of the same character are considered to be identical within each
+language. (Of course, it may take a specialist to recognize the
+related form; the point is that the relations are standardized, despite
+the differing shapes.)
+
+ In some cases, the differences will be significant enough that it is
+actually possible to identify two or more distinct shapes that both
+represent the same character. For example, the lowercase letters `a'
+and `g' each have two distinct possible shapes--the `a' can optionally
+have a curved tail projecting off the top, and the `g' can be formed
+either of two loops, or of one loop and a tail hanging off the bottom.
+Such distinct possible shapes of a character are called "glyphs". The
+important characteristic of two glyphs making up the same character is
+that the choice between one or the other is purely stylistic and has no
+linguistic effect on a word (this is the reason why a capital `A' and
+lowercase `a' are different characters rather than different
+glyphs--e.g. `Aspen' is a city while `aspen' is a kind of tree).
+
+ Note that "character" and "glyph" are used differently here than
+elsewhere in XEmacs.
+
+ A "character set" is essentially a set of related characters. ASCII,
+for example, is a set of 94 characters (or 128, if you count
+non-printing characters). Other character sets are ISO8859-1 (ASCII
+plus various accented characters and other international symbols), JIS
+X 0201 (ASCII, more or less, plus half-width Katakana), JIS X 0208
+(Japanese Kanji), JIS X 0212 (a second set of less-used Japanese Kanji),
+GB2312 (Mainland Chinese Hanzi), etc.
+
+ The definition of a character set will implicitly or explicitly give
+it an "ordering", a way of assigning a number to each character in the
+set. For many character sets, there is a natural ordering, for example
+the "ABC" ordering of the Roman letters. But it is not clear whether
+digits should come before or after the letters, and in fact different
+European languages treat the ordering of accented characters
+differently. It is useful to use the natural order where available, of
+course. The number assigned to any particular character is called the
+character's "code point". (Within a given character set, each
+character has a unique code point. Thus the word "set" is ill-chosen;
+different orderings of the same characters are different character sets.
+Identifying characters is simple enough for alphabetic character sets,
+but the difference in ordering can cause great headaches when the same
+thousands of characters are used by different cultures as in the Hanzi.)
+
+ A code point may be broken into a number of "position codes". The
+number of position codes required to index a particular character in a
+character set is called the "dimension" of the character set. For
+practical purposes, a position code may be thought of as a byte-sized
+index. The printing characters of ASCII, being a relatively small
+character set, is of dimension one, and each character in the set is
+indexed using a single position code, in the range 1 through 94. Use of
+this unusual range, rather than the familiar 33 through 126, is an
+intentional abstraction; to understand the programming issues you must
+break the equation between character sets and encodings.
+
+ JIS X 0208, i.e. Japanese Kanji, has thousands of characters, and is
+of dimension two - every character is indexed by two position codes,
+each in the range 1 through 94. (This number "94" is not a
+coincidence; we shall see that the JIS position codes were chosen so
+that JIS kanji could be encoded without using codes that in ASCII are
+associated with device control functions.) Note that the choice of the
+range here is somewhat arbitrary. You could just as easily index the
+printing characters in ASCII using numbers in the range 0 through 93, 2
+through 95, 3 through 96, etc. In fact, the standardized _encoding_
+for the ASCII _character set_ uses the range 33 through 126.
+
+ An "encoding" is a way of numerically representing characters from
+one or more character sets into a stream of like-sized numerical values
+called "words"; typically these are 8-bit, 16-bit, or 32-bit
+quantities. If an encoding encompasses only one character set, then the
+position codes for the characters in that character set could be used
+directly. (This is the case with the trivial cipher used by children,
+assigning 1 to `A', 2 to `B', and so on.) However, even with ASCII,
+other considerations intrude. For example, why are the upper- and
+lowercase alphabets separated by 8 characters? Why do the digits start
+with `0' being assigned the code 48? In both cases because semantically
+interesting operations (case conversion and numerical value extraction)
+become convenient masking operations. Other artificial aspects (the
+control characters being assigned to codes 0-31 and 127) are historical
+accidents. (The use of 127 for `DEL' is an artifact of the "punch
+once" nature of paper tape, for example.)
+
+ Naive use of the position code is not possible, however, if more than
+one character set is to be used in the encoding. For example, printed
+Japanese text typically requires characters from multiple character sets
+- ASCII, JIS X 0208, and JIS X 0212, to be specific. Each of these is
+indexed using one or more position codes in the range 1 through 94, so
+the position codes could not be used directly or there would be no way
+to tell which character was meant. Different Japanese encodings handle
+this differently - JIS uses special escape characters to denote
+different character sets; EUC sets the high bit of the position codes
+for JIS X 0208 and JIS X 0212, and puts a special extra byte before each
+JIS X 0212 character; etc. (JIS, EUC, and most of the other encodings
+you will encounter in files are 7-bit or 8-bit encodings. There is one
+common 16-bit encoding, which is Unicode; this strives to represent all
+the world's characters in a single large character set. 32-bit
+encodings are often used internally in programs, such as XEmacs with
+MULE support, to simplify the code that manipulates them; however, they
+are not used externally because they are not very space-efficient.)
+
+ A general method of handling text using multiple character sets
+(whether for multilingual text, or simply text in an extremely
+complicated single language like Japanese) is defined in the
+international standard ISO 2022. ISO 2022 will be discussed in more
+detail later (*note ISO 2022::), but for now suffice it to say that text
+needs control functions (at least spacing), and if escape sequences are
+to be used, an escape sequence introducer. It was decided to make all
+text streams compatible with ASCII in the sense that the codes 0-31
+(and 128-159) would always be control codes, never graphic characters,
+and where defined by the character set the `SPC' character would be
+assigned code 32, and `DEL' would be assigned 127. Thus there are 94
+code points remaining if 7 bits are used. This is the reason that most
+character sets are defined using position codes in the range 1 through
+94. Then ISO 2022 compatible encodings are produced by shifting the
+position codes 1 to 94 into character codes 33 to 126, or (if 8 bit
+codes are available) into character codes 161 to 254.
+
+ Encodings are classified as either "modal" or "non-modal". In a
+"modal encoding", there are multiple states that the encoding can be
+in, and the interpretation of the values in the stream depends on the
+current global state of the encoding. Special values in the encoding,
+called "escape sequences", are used to change the global state. JIS,
+for example, is a modal encoding. The bytes `ESC $ B' indicate that,
+from then on, bytes are to be interpreted as position codes for JIS X
+0208, rather than as ASCII. This effect is cancelled using the bytes
+`ESC ( B', which mean "switch from whatever the current state is to
+ASCII". To switch to JIS X 0212, the escape sequence `ESC $ ( D'.
+(Note that here, as is common, the escape sequences do in fact begin
+with `ESC'. This is not necessarily the case, however. Some encodings
+use control characters called "locking shifts" (effect persists until
+cancelled) to switch character sets.)
+
+ A "non-modal encoding" has no global state that extends past the
+character currently being interpreted. EUC, for example, is a
+non-modal encoding. Characters in JIS X 0208 are encoded by setting
+the high bit of the position codes, and characters in JIS X 0212 are
+encoded by doing the same but also prefixing the character with the
+byte 0x8F.
+
+ The advantage of a modal encoding is that it is generally more
+space-efficient, and is easily extendable because there are essentially
+an arbitrary number of escape sequences that can be created. The
+disadvantage, however, is that it is much more difficult to work with
+if it is not being processed in a sequential manner. In the non-modal
+EUC encoding, for example, the byte 0x41 always refers to the letter
+`A'; whereas in JIS, it could either be the letter `A', or one of the
+two position codes in a JIS X 0208 character, or one of the two
+position codes in a JIS X 0212 character. Determining exactly which
+one is meant could be difficult and time-consuming if the previous
+bytes in the string have not already been processed, or impossible if
+they are drawn from an external stream that cannot be rewound.
+
+ Non-modal encodings are further divided into "fixed-width" and
+"variable-width" formats. A fixed-width encoding always uses the same
+number of words per character, whereas a variable-width encoding does
+not. EUC is a good example of a variable-width encoding: one to three
+bytes are used per character, depending on the character set. 16-bit
+and 32-bit encodings are nearly always fixed-width, and this is in fact
+one of the main reasons for using an encoding with a larger word size.
+The advantages of fixed-width encodings should be obvious. The
+advantages of variable-width encodings are that they are generally more
+space-efficient and allow for compatibility with existing 8-bit
+encodings such as ASCII. (For example, in Unicode ASCII characters are
+simply promoted to a 16-bit representation. That means that every
+ASCII character contains a `NUL' byte; evidently all of the standard
+string manipulation functions will lose badly in a fixed-width Unicode
+environment.)
+
+ The bytes in an 8-bit encoding are often referred to as "octets"
+rather than simply as bytes. This terminology dates back to the days
+before 8-bit bytes were universal, when some computers had 9-bit bytes,
+others had 10-bit bytes, etc.
\1f
-File: lispref.info, Node: Building XEmacs and Object Allocation, Next: Standard Errors, Prev: Tips, Up: Top
+File: lispref.info, Node: Charsets, Next: MULE Characters, Prev: Internationalization Terminology, Up: MULE
-Building XEmacs; Allocation of Objects
-**************************************
+Charsets
+========
- This chapter describes how the runnable XEmacs executable is dumped
-with the preloaded Lisp libraries in it and how storage is allocated.
+ A "charset" in MULE is an object that encapsulates a particular
+character set as well as an ordering of those characters. Charsets are
+permanent objects and are named using symbols, like faces.
- There is an entire separate document, the `XEmacs Internals Manual',
-devoted to the internals of XEmacs from the perspective of the C
-programmer. It contains much more detailed information about the build
-process, the allocation and garbage-collection process, and other
-aspects related to the internals of XEmacs.
+ - Function: charsetp object
+ This function returns non-`nil' if OBJECT is a charset.
* Menu:
-* Building XEmacs:: How to preload Lisp libraries into XEmacs.
-* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
-* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
+* Charset Properties:: Properties of a charset.
+* Basic Charset Functions:: Functions for working with charsets.
+* Charset Property Functions:: Functions for accessing charset properties.
+* Predefined Charsets:: Predefined charset objects.
+
+\1f
+File: lispref.info, Node: Charset Properties, Next: Basic Charset Functions, Up: Charsets
+
+Charset Properties
+------------------
+
+ Charsets have the following properties:
+
+`name'
+ A symbol naming the charset. Every charset must have a different
+ name; this allows a charset to be referred to using its name
+ rather than the actual charset object.
+
+`doc-string'
+ A documentation string describing the charset.
+
+`registry'
+ A regular expression matching the font registry field for this
+ character set. For example, both the `ascii' and `latin-iso8859-1'
+ charsets use the registry `"ISO8859-1"'. This field is used to
+ choose an appropriate font when the user gives a general font
+ specification such as `-*-courier-medium-r-*-140-*', i.e. a
+ 14-point upright medium-weight Courier font.
+
+`dimension'
+ Number of position codes used to index a character in the
+ character set. XEmacs/MULE can only handle character sets of
+ dimension 1 or 2. This property defaults to 1.
+
+`chars'
+ Number of characters in each dimension. In XEmacs/MULE, the only
+ allowed values are 94 or 96. (There are a couple of pre-defined
+ character sets, such as ASCII, that do not follow this, but you
+ cannot define new ones like this.) Defaults to 94. Note that if
+ the dimension is 2, the character set thus described is 94x94 or
+ 96x96.
+
+`columns'
+ Number of columns used to display a character in this charset.
+ Only used in TTY mode. (Under X, the actual width of a character
+ can be derived from the font used to display the characters.) If
+ unspecified, defaults to the dimension. (This is almost always the
+ correct value, because character sets with dimension 2 are usually
+ ideograph character sets, which need two columns to display the
+ intricate ideographs.)
+
+`direction'
+ A symbol, either `l2r' (left-to-right) or `r2l' (right-to-left).
+ Defaults to `l2r'. This specifies the direction that the text
+ should be displayed in, and will be left-to-right for most
+ charsets but right-to-left for Hebrew and Arabic. (Right-to-left
+ display is not currently implemented.)
+
+`final'
+ Final byte of the standard ISO 2022 escape sequence designating
+ this charset. Must be supplied. Each combination of (DIMENSION,
+ CHARS) defines a separate namespace for final bytes, and each
+ charset within a particular namespace must have a different final
+ byte. Note that ISO 2022 restricts the final byte to the range
+ 0x30 - 0x7E if dimension == 1, and 0x30 - 0x5F if dimension == 2.
+ Note also that final bytes in the range 0x30 - 0x3F are reserved
+ for user-defined (not official) character sets. For more
+ information on ISO 2022, see *Note Coding Systems::.
+
+`graphic'
+ 0 (use left half of font on output) or 1 (use right half of font on
+ output). Defaults to 0. This specifies how to convert the
+ position codes that index a character in a character set into an
+ index into the font used to display the character set. With
+ `graphic' set to 0, position codes 33 through 126 map to font
+ indices 33 through 126; with it set to 1, position codes 33
+ through 126 map to font indices 161 through 254 (i.e. the same
+ number but with the high bit set). For example, for a font whose
+ registry is ISO8859-1, the left half of the font (octets 0x20 -
+ 0x7F) is the `ascii' charset, while the right half (octets 0xA0 -
+ 0xFF) is the `latin-iso8859-1' charset.
+
+`ccl-program'
+ A compiled CCL program used to convert a character in this charset
+ into an index into the font. This is in addition to the `graphic'
+ property. If a CCL program is defined, the position codes of a
+ character will first be processed according to `graphic' and then
+ passed through the CCL program, with the resulting values used to
+ index the font.
+
+ This is used, for example, in the Big5 character set (used in
+ Taiwan). This character set is not ISO-2022-compliant, and its
+ size (94x157) does not fit within the maximum 96x96 size of
+ ISO-2022-compliant character sets. As a result, XEmacs/MULE
+ splits it (in a rather complex fashion, so as to group the most
+ commonly used characters together) into two charset objects
+ (`big5-1' and `big5-2'), each of size 94x94, and each charset
+ object uses a CCL program to convert the modified position codes
+ back into standard Big5 indices to retrieve a character from a
+ Big5 font.
+
+ Most of the above properties can only be set when the charset is
+initialized, and cannot be changed later. *Note Charset Property
+Functions::.
+
+\1f
+File: lispref.info, Node: Basic Charset Functions, Next: Charset Property Functions, Prev: Charset Properties, Up: Charsets
+
+Basic Charset Functions
+-----------------------
+
+ - Function: find-charset charset-or-name
+ This function retrieves the charset of the given name. If
+ CHARSET-OR-NAME is a charset object, it is simply returned.
+ Otherwise, CHARSET-OR-NAME should be a symbol. If there is no
+ such charset, `nil' is returned. Otherwise the associated charset
+ object is returned.
+
+ - Function: get-charset name
+ This function retrieves the charset of the given name. Same as
+ `find-charset' except an error is signalled if there is no such
+ charset instead of returning `nil'.
+
+ - Function: charset-list
+ This function returns a list of the names of all defined charsets.
+
+ - Function: make-charset name doc-string props
+ This function defines a new character set. This function is for
+ use with MULE support. NAME is a symbol, the name by which the
+ character set is normally referred. DOC-STRING is a string
+ describing the character set. PROPS is a property list,
+ describing the specific nature of the character set. The
+ recognized properties are `registry', `dimension', `columns',
+ `chars', `final', `graphic', `direction', and `ccl-program', as
+ previously described.
+
+ - Function: make-reverse-direction-charset charset new-name
+ This function makes a charset equivalent to CHARSET but which goes
+ in the opposite direction. NEW-NAME is the name of the new
+ charset. The new charset is returned.
+
+ - Function: charset-from-attributes dimension chars final &optional
+ direction
+ This function returns a charset with the given DIMENSION, CHARS,
+ FINAL, and DIRECTION. If DIRECTION is omitted, both directions
+ will be checked (left-to-right will be returned if character sets
+ exist for both directions).
+
+ - Function: charset-reverse-direction-charset charset
+ This function returns the charset (if any) with the same dimension,
+ number of characters, and final byte as CHARSET, but which is
+ displayed in the opposite direction.
+
+\1f
+File: lispref.info, Node: Charset Property Functions, Next: Predefined Charsets, Prev: Basic Charset Functions, Up: Charsets
+
+Charset Property Functions
+--------------------------
+
+ All of these functions accept either a charset name or charset
+object.
+
+ - Function: charset-property charset prop
+ This function returns property PROP of CHARSET. *Note Charset
+ Properties::.
+
+ Convenience functions are also provided for retrieving individual
+properties of a charset.
+
+ - Function: charset-name charset
+ This function returns the name of CHARSET. This will be a symbol.
+
+ - Function: charset-doc-string charset
+ This function returns the doc string of CHARSET.
+
+ - Function: charset-registry charset
+ This function returns the registry of CHARSET.
+
+ - Function: charset-dimension charset
+ This function returns the dimension of CHARSET.
+
+ - Function: charset-chars charset
+ This function returns the number of characters per dimension of
+ CHARSET.
+
+ - Function: charset-columns charset
+ This function returns the number of display columns per character
+ (in TTY mode) of CHARSET.
+
+ - Function: charset-direction charset
+ This function returns the display direction of CHARSET--either
+ `l2r' or `r2l'.
+
+ - Function: charset-final charset
+ This function returns the final byte of the ISO 2022 escape
+ sequence designating CHARSET.
+
+ - Function: charset-graphic charset
+ This function returns either 0 or 1, depending on whether the
+ position codes of characters in CHARSET map to the left or right
+ half of their font, respectively.
+
+ - Function: charset-ccl-program charset
+ This function returns the CCL program, if any, for converting
+ position codes of characters in CHARSET into font indices.
+
+ The only property of a charset that can currently be set after the
+charset has been created is the CCL program.
+
+ - Function: set-charset-ccl-program charset ccl-program
+ This function sets the `ccl-program' property of CHARSET to
+ CCL-PROGRAM.
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Building XEmacs, Next: Pure Storage, Up: Building XEmacs and Object Allocation
-
-Building XEmacs
-===============
-
- This section explains the steps involved in building the XEmacs
-executable. You don't have to know this material to build and install
-XEmacs, since the makefiles do all these things automatically. This
-information is pertinent to XEmacs maintenance.
-
- The `XEmacs Internals Manual' contains more information about this.
-
- Compilation of the C source files in the `src' directory produces an
-executable file called `temacs', also called a "bare impure XEmacs".
-It contains the XEmacs Lisp interpreter and I/O routines, but not the
-editing commands.
-
- Before XEmacs is actually usable, a number of Lisp files need to be
-loaded. These define all the editing commands, plus most of the startup
-code and many very basic Lisp primitives. This is accomplished by
-loading the file `loadup.el', which in turn loads all of the other
-standardly-loaded Lisp files.
-
- It takes a substantial time to load the standard Lisp files.
-Luckily, you don't have to do this each time you run XEmacs; `temacs'
-can dump out an executable program called `xemacs' that has these files
-preloaded. `xemacs' starts more quickly because it does not need to
-load the files. This is the XEmacs executable that is normally
-installed.
-
- To create `xemacs', use the command `temacs -batch -l loadup dump'.
-The purpose of `-batch' here is to tell `temacs' to run in
-non-interactive, command-line mode. (`temacs' can _only_ run in this
-fashion. Part of the code required to initialize frames and faces is
-in Lisp, and must be loaded before XEmacs is able to create any frames.)
-The argument `dump' tells `loadup.el' to dump a new executable named
-`xemacs'.
-
- The dumping process is highly system-specific, and some operating
-systems don't support dumping. On those systems, you must start XEmacs
-with the `temacs -batch -l loadup run-temacs' command each time you use
-it. This takes a substantial time, but since you need to start Emacs
-once a day at most--or once a week if you never log out--the extra time
-is not too severe a problem. (In older versions of Emacs, you started
-Emacs from `temacs' using `temacs -l loadup'.)
-
- You are free to start XEmacs directly from `temacs' if you want,
-even if there is already a dumped `xemacs'. Normally you wouldn't want
-to do that; but the Makefiles do this when you rebuild XEmacs using
-`make all-elc', which builds XEmacs and simultaneously compiles any
-out-of-date Lisp files. (You need `xemacs' in order to compile Lisp
-files. However, you also need the compiled Lisp files in order to dump
-out `xemacs'. If both of these are missing or corrupted, you are out
-of luck unless you're able to bootstrap `xemacs' from `temacs'. Note
-that `make all-elc' actually loads the alternative loadup file
-`loadup-el.el', which works like `loadup.el' but disables the
-pure-copying process and forces XEmacs to ignore any compiled Lisp
-files even if they exist.)
-
- You can specify additional files to preload by writing a library
-named `site-load.el' that loads them. You may need to increase the
-value of `PURESIZE', in `src/puresize.h', to make room for the
-additional files. You should _not_ modify this file directly, however;
-instead, use the `--puresize' configuration option. (If you run out of
-pure space while dumping `xemacs', you will be told how much pure space
-you actually will need.) However, the advantage of preloading
-additional files decreases as machines get faster. On modern machines,
-it is often not advisable, especially if the Lisp code is on a file
-system local to the machine running XEmacs.
-
- You can specify other Lisp expressions to execute just before dumping
-by putting them in a library named `site-init.el'. However, if they
-might alter the behavior that users expect from an ordinary unmodified
-XEmacs, it is better to put them in `default.el', so that users can
-override them if they wish. *Note Start-up Summary::.
-
- Before `loadup.el' dumps the new executable, it finds the
-documentation strings for primitive and preloaded functions (and
-variables) in the file where they are stored, by calling
-`Snarf-documentation' (*note Accessing Documentation::). These strings
-were moved out of the `xemacs' executable to make it smaller. *Note
-Documentation Basics::.
-
- - Function: dump-emacs to-file from-file
- This function dumps the current state of XEmacs into an executable
- file TO-FILE. It takes symbols from FROM-FILE (this is normally
- the executable file `temacs').
-
- If you use this function in an XEmacs that was already dumped, you
- must set `command-line-processed' to `nil' first for good results.
- *Note Command Line Arguments::.
-
- - Function: run-emacs-from-temacs &rest args
- This is the function that implements the `run-temacs' command-line
- argument. It is called from `loadup.el' as appropriate. You
- should most emphatically _not_ call this yourself; it will
- reinitialize your XEmacs process and you'll be sorry.
-
- - Command: emacs-version
- This function returns a string describing the version of XEmacs
- that is running. It is useful to include this string in bug
- reports.
-
- (emacs-version)
- => "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29)
- of Mon Apr 7 1997 on altair.xemacs.org"
-
- Called interactively, the function prints the same information in
- the echo area.
-
- - Variable: emacs-build-time
- The value of this variable is the time at which XEmacs was built
- at the local site.
-
- emacs-build-time "Mon Apr 7 20:28:52 1997"
- =>
-
- - Variable: emacs-version
- The value of this variable is the version of Emacs being run. It
- is a string, e.g. `"20.1 XEmacs Lucid"'.
-
- The following two variables did not exist before FSF GNU Emacs
-version 19.23 and XEmacs version 19.10, which reduces their usefulness
-at present, but we hope they will be convenient in the future.
-
- - Variable: emacs-major-version
- The major version number of Emacs, as an integer. For XEmacs
- version 20.1, the value is 20.
-
- - Variable: emacs-minor-version
- The minor version number of Emacs, as an integer. For XEmacs
- version 20.1, the value is 1.
-
-\1f
-File: lispref.info, Node: Pure Storage, Next: Garbage Collection, Prev: Building XEmacs, Up: Building XEmacs and Object Allocation
-
-Pure Storage
-============
-
- XEmacs Lisp uses two kinds of storage for user-created Lisp objects:
-"normal storage" and "pure storage". Normal storage is where all the
-new data created during an XEmacs session is kept; see the following
-section for information on normal storage. Pure storage is used for
-certain data in the preloaded standard Lisp files--data that should
-never change during actual use of XEmacs.
-
- Pure storage is allocated only while `temacs' is loading the
-standard preloaded Lisp libraries. In the file `xemacs', it is marked
-as read-only (on operating systems that permit this), so that the
-memory space can be shared by all the XEmacs jobs running on the machine
-at once. Pure storage is not expandable; a fixed amount is allocated
-when XEmacs is compiled, and if that is not sufficient for the preloaded
-libraries, `temacs' aborts with an error message. If that happens, you
-must increase the compilation parameter `PURESIZE' using the
-`--puresize' option to `configure'. This normally won't happen unless
-you try to preload additional libraries or add features to the standard
-ones.
-
- - Function: purecopy object
- This function makes a copy of OBJECT in pure storage and returns
- it. It copies strings by simply making a new string with the same
- characters in pure storage. It recursively copies the contents of
- vectors and cons cells. It does not make copies of other objects
- such as symbols, but just returns them unchanged. It signals an
- error if asked to copy markers.
-
- This function is a no-op except while XEmacs is being built and
- dumped; it is usually called only in the file
- `xemacs/lisp/prim/loaddefs.el', but a few packages call it just in
- case you decide to preload them.
-
- - Variable: pure-bytes-used
- The value of this variable is the number of bytes of pure storage
- allocated so far. Typically, in a dumped XEmacs, this number is
- very close to the total amount of pure storage available--if it
- were not, we would preallocate less.
-
- - Variable: purify-flag
- This variable determines whether `defun' should make a copy of the
- function definition in pure storage. If it is non-`nil', then the
- function definition is copied into pure storage.
-
- This flag is `t' while loading all of the basic functions for
- building XEmacs initially (allowing those functions to be sharable
- and non-collectible). Dumping XEmacs as an executable always
- writes `nil' in this variable, regardless of the value it actually
- has before and after dumping.
-
- You should not change this flag in a running XEmacs.
+File: lispref.info, Node: Predefined Charsets, Prev: Charset Property Functions, Up: Charsets
+
+Predefined Charsets
+-------------------
+
+ The following charsets are predefined in the C code.
+
+ Name Type Fi Gr Dir Registry
+ --------------------------------------------------------------
+ ascii 94 B 0 l2r ISO8859-1
+ control-1 94 0 l2r ---
+ latin-iso8859-1 94 A 1 l2r ISO8859-1
+ latin-iso8859-2 96 B 1 l2r ISO8859-2
+ latin-iso8859-3 96 C 1 l2r ISO8859-3
+ latin-iso8859-4 96 D 1 l2r ISO8859-4
+ cyrillic-iso8859-5 96 L 1 l2r ISO8859-5
+ arabic-iso8859-6 96 G 1 r2l ISO8859-6
+ greek-iso8859-7 96 F 1 l2r ISO8859-7
+ hebrew-iso8859-8 96 H 1 r2l ISO8859-8
+ latin-iso8859-9 96 M 1 l2r ISO8859-9
+ thai-tis620 96 T 1 l2r TIS620
+ katakana-jisx0201 94 I 1 l2r JISX0201.1976
+ latin-jisx0201 94 J 0 l2r JISX0201.1976
+ japanese-jisx0208-1978 94x94 @ 0 l2r JISX0208.1978
+ japanese-jisx0208 94x94 B 0 l2r JISX0208.19(83|90)
+ japanese-jisx0212 94x94 D 0 l2r JISX0212
+ chinese-gb2312 94x94 A 0 l2r GB2312
+ chinese-cns11643-1 94x94 G 0 l2r CNS11643.1
+ chinese-cns11643-2 94x94 H 0 l2r CNS11643.2
+ chinese-big5-1 94x94 0 0 l2r Big5
+ chinese-big5-2 94x94 1 0 l2r Big5
+ korean-ksc5601 94x94 C 0 l2r KSC5601
+ composite 96x96 0 l2r ---
+
+ The following charsets are predefined in the Lisp code.
+
+ Name Type Fi Gr Dir Registry
+ --------------------------------------------------------------
+ arabic-digit 94 2 0 l2r MuleArabic-0
+ arabic-1-column 94 3 0 r2l MuleArabic-1
+ arabic-2-column 94 4 0 r2l MuleArabic-2
+ sisheng 94 0 0 l2r sisheng_cwnn\|OMRON_UDC_ZH
+ chinese-cns11643-3 94x94 I 0 l2r CNS11643.1
+ chinese-cns11643-4 94x94 J 0 l2r CNS11643.1
+ chinese-cns11643-5 94x94 K 0 l2r CNS11643.1
+ chinese-cns11643-6 94x94 L 0 l2r CNS11643.1
+ chinese-cns11643-7 94x94 M 0 l2r CNS11643.1
+ ethiopic 94x94 2 0 l2r Ethio
+ ascii-r2l 94 B 0 r2l ISO8859-1
+ ipa 96 0 1 l2r MuleIPA
+ vietnamese-lower 96 1 1 l2r VISCII1.1
+ vietnamese-upper 96 2 1 l2r VISCII1.1
+
+ For all of the above charsets, the dimension and number of columns
+are the same.
+
+ Note that ASCII, Control-1, and Composite are handled specially.
+This is why some of the fields are blank; and some of the filled-in
+fields (e.g. the type) are not really accurate.
\1f
-File: lispref.info, Node: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation
-
-Garbage Collection
-==================
-
- When a program creates a list or the user defines a new function
-(such as by loading a library), that data is placed in normal storage.
-If normal storage runs low, then XEmacs asks the operating system to
-allocate more memory in blocks of 2k bytes. Each block is used for one
-type of Lisp object, so symbols, cons cells, markers, etc., are
-segregated in distinct blocks in memory. (Vectors, long strings,
-buffers and certain other editing types, which are fairly large, are
-allocated in individual blocks, one per object, while small strings are
-packed into blocks of 8k bytes. [More correctly, a string is allocated
-in two sections: a fixed size chunk containing the length, list of
-extents, etc.; and a chunk containing the actual characters in the
-string. It is this latter chunk that is either allocated individually
-or packed into 8k blocks. The fixed size chunk is packed into 2k
-blocks, as for conses, markers, etc.])
-
- It is quite common to use some storage for a while, then release it
-by (for example) killing a buffer or deleting the last pointer to an
-object. XEmacs provides a "garbage collector" to reclaim this
-abandoned storage. (This name is traditional, but "garbage recycler"
-might be a more intuitive metaphor for this facility.)
-
- The garbage collector operates by finding and marking all Lisp
-objects that are still accessible to Lisp programs. To begin with, it
-assumes all the symbols, their values and associated function
-definitions, and any data presently on the stack, are accessible. Any
-objects that can be reached indirectly through other accessible objects
-are also accessible.
-
- When marking is finished, all objects still unmarked are garbage. No
-matter what the Lisp program or the user does, it is impossible to refer
-to them, since there is no longer a way to reach them. Their space
-might as well be reused, since no one will miss them. The second
-("sweep") phase of the garbage collector arranges to reuse them.
-
- The sweep phase puts unused cons cells onto a "free list" for future
-allocation; likewise for symbols, markers, extents, events, floats,
-compiled-function objects, and the fixed-size portion of strings. It
-compacts the accessible small string-chars chunks so they occupy fewer
-8k blocks; then it frees the other 8k blocks. Vectors, buffers,
-windows, and other large objects are individually allocated and freed
-using `malloc' and `free'.
-
- Common Lisp note: unlike other Lisps, XEmacs Lisp does not call
- the garbage collector when the free list is empty. Instead, it
- simply requests the operating system to allocate more storage, and
- processing continues until `gc-cons-threshold' bytes have been
- used.
-
- This means that you can make sure that the garbage collector will
- not run during a certain portion of a Lisp program by calling the
- garbage collector explicitly just before it (provided that portion
- of the program does not use so much space as to force a second
- garbage collection).
-
- - Command: garbage-collect
- This command runs a garbage collection, and returns information on
- the amount of space in use. (Garbage collection can also occur
- spontaneously if you use more than `gc-cons-threshold' bytes of
- Lisp data since the previous garbage collection.)
-
- `garbage-collect' returns a list containing the following
- information:
-
- ((USED-CONSES . FREE-CONSES)
- (USED-SYMS . FREE-SYMS)
- (USED-MARKERS . FREE-MARKERS)
- USED-STRING-CHARS
- USED-VECTOR-SLOTS
- (PLIST))
-
- => ((73362 . 8325) (13718 . 164)
- (5089 . 5098) 949121 118677
- (conses-used 73362 conses-free 8329 cons-storage 658168
- symbols-used 13718 symbols-free 164 symbol-storage 335216
- bit-vectors-used 0 bit-vectors-total-length 0
- bit-vector-storage 0 vectors-used 7882
- vectors-total-length 118677 vector-storage 537764
- compiled-functions-used 1336 compiled-functions-free 37
- compiled-function-storage 44440 short-strings-used 28829
- long-strings-used 2 strings-free 7722
- short-strings-total-length 916657 short-string-storage 1179648
- long-strings-total-length 32464 string-header-storage 441504
- floats-used 3 floats-free 43 float-storage 2044 markers-used 5089
- markers-free 5098 marker-storage 245280 events-used 103
- events-free 835 event-storage 110656 extents-used 10519
- extents-free 2718 extent-storage 372736
- extent-auxiliarys-used 111 extent-auxiliarys-freed 3
- extent-auxiliary-storage 4440 window-configurations-used 39
- window-configurations-on-free-list 5
- window-configurations-freed 10 window-configuration-storage 9492
- popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62
- toolbar-button-storage 4960 toolbar-datas-used 12
- toolbar-data-storage 240 symbol-value-buffer-locals-used 182
- symbol-value-buffer-local-storage 5824
- symbol-value-lisp-magics-used 22
- symbol-value-lisp-magic-storage 1496
- symbol-value-varaliases-used 43
- symbol-value-varalias-storage 1032 opaque-lists-used 2
- opaque-list-storage 48 color-instances-used 12
- color-instance-storage 288 font-instances-used 5
- font-instance-storage 180 opaques-used 11 opaque-storage 312
- range-tables-used 1 range-table-storage 16 faces-used 34
- face-storage 2584 glyphs-used 124 glyph-storage 4464
- specifiers-used 775 specifier-storage 43869 weak-lists-used 786
- weak-list-storage 18864 char-tables-used 40
- char-table-storage 41920 buffers-used 25 buffer-storage 7000
- extent-infos-used 457 extent-infos-freed 73
- extent-info-storage 9140 keymaps-used 275 keymap-storage 12100
- consoles-used 4 console-storage 384 command-builders-used 2
- command-builder-storage 120 devices-used 2 device-storage 344
- frames-used 3 frame-storage 624 image-instances-used 47
- image-instance-storage 3008 windows-used 27 windows-freed 2
- window-storage 9180 lcrecord-lists-used 15
- lcrecord-list-storage 360 hash-tables-used 631
- hash-table-storage 25240 streams-used 1 streams-on-free-list 3
- streams-freed 12 stream-storage 91))
-
- Here is a table explaining each element:
-
- USED-CONSES
- The number of cons cells in use.
-
- FREE-CONSES
- The number of cons cells for which space has been obtained
- from the operating system, but that are not currently being
- used.
-
- USED-SYMS
- The number of symbols in use.
-
- FREE-SYMS
- The number of symbols for which space has been obtained from
- the operating system, but that are not currently being used.
-
- USED-MARKERS
- The number of markers in use.
-
- FREE-MARKERS
- The number of markers for which space has been obtained from
- the operating system, but that are not currently being used.
-
- USED-STRING-CHARS
- The total size of all strings, in characters.
-
- USED-VECTOR-SLOTS
- The total number of elements of existing vectors.
-
- PLIST
- A list of alternating keyword/value pairs providing more
- detailed information. (As you can see above, quite a lot of
- information is provided.)
-
- - User Option: gc-cons-threshold
- The value of this variable is the number of bytes of storage that
- must be allocated for Lisp objects after one garbage collection in
- order to trigger another garbage collection. A cons cell counts
- as eight bytes, a string as one byte per character plus a few
- bytes of overhead, and so on; space allocated to the contents of
- buffers does not count. Note that the subsequent garbage
- collection does not happen immediately when the threshold is
- exhausted, but only the next time the Lisp evaluator is called.
-
- The initial threshold value is 500,000. If you specify a larger
- value, garbage collection will happen less often. This reduces the
- amount of time spent garbage collecting, but increases total
- memory use. You may want to do this when running a program that
- creates lots of Lisp data.
-
- You can make collections more frequent by specifying a smaller
- value, down to 10,000. A value less than 10,000 will remain in
- effect only until the subsequent garbage collection, at which time
- `garbage-collect' will set the threshold back to 10,000. (This does
- not apply if XEmacs was configured with `--debug'. Therefore, be
- careful when setting `gc-cons-threshold' in that case!)
-
- - Function: memory-limit
- This function returns the address of the last byte XEmacs has
- allocated, divided by 1024. We divide the value by 1024 to make
- sure it fits in a Lisp integer.
-
- You can use this to get a general idea of how your actions affect
- the memory usage.
-
- - Variable: pre-gc-hook
- This is a normal hook to be run just before each garbage
- collection. Interrupts, garbage collection, and errors are
- inhibited while this hook runs, so be extremely careful in what
- you add here. In particular, avoid consing, and do not interact
- with the user.
-
- - Variable: post-gc-hook
- This is a normal hook to be run just after each garbage collection.
- Interrupts, garbage collection, and errors are inhibited while
- this hook runs, so be extremely careful in what you add here. In
- particular, avoid consing, and do not interact with the user.
-
- - Variable: gc-message
- This is a string to print to indicate that a garbage collection is
- in progress. This is printed in the echo area. If the selected
- frame is on a window system and `gc-pointer-glyph' specifies a
- value (i.e. a pointer image instance) in the domain of the
- selected frame, the mouse cursor will change instead of this
- message being printed.
-
- - Glyph: gc-pointer-glyph
- This holds the pointer glyph used to indicate that a garbage
- collection is in progress. If the selected window is on a window
- system and this glyph specifies a value (i.e. a pointer image
- instance) in the domain of the selected window, the cursor will be
- changed as specified during garbage collection. Otherwise, a
- message will be printed in the echo area, as controlled by
- `gc-message'. *Note Glyphs::.
-
- If XEmacs was configured with `--debug', you can set the following
-two variables to get direct information about all the allocation that
-is happening in a segment of Lisp code.
-
- - Variable: debug-allocation
- If non-zero, print out information to stderr about all objects
- allocated.
-
- - Variable: debug-allocation-backtrace
- Length (in stack frames) of short backtrace printed out by
- `debug-allocation'.
-
-\1f
-File: lispref.info, Node: Standard Errors, Next: Standard Buffer-Local Variables, Prev: Building XEmacs and Object Allocation, Up: Top
-
-Standard Errors
-***************
-
- Here is the complete list of the error symbols in standard Emacs,
-grouped by concept. The list includes each symbol's message (on the
-`error-message' property of the symbol) and a cross reference to a
-description of how the error can occur.
-
- Each error symbol has an `error-conditions' property that is a list
-of symbols. Normally this list includes the error symbol itself and
-the symbol `error'. Occasionally it includes additional symbols, which
-are intermediate classifications, narrower than `error' but broader
-than a single error symbol. For example, all the errors in accessing
-files have the condition `file-error'.
-
- As a special exception, the error symbol `quit' does not have the
-condition `error', because quitting is not considered an error.
-
- *Note Errors::, for an explanation of how errors are generated and
-handled.
-
-`SYMBOL'
- STRING; REFERENCE.
-
-`error'
- `"error"'
- *Note Errors::.
-
-`quit'
- `"Quit"'
- *Note Quitting::.
-
-`args-out-of-range'
- `"Args out of range"'
- *Note Sequences Arrays Vectors::.
-
-`arith-error'
- `"Arithmetic error"'
- See `/' and `%' in *Note Numbers::.
-
-`beginning-of-buffer'
- `"Beginning of buffer"'
- *Note Motion::.
-
-`buffer-read-only'
- `"Buffer is read-only"'
- *Note Read Only Buffers::.
-
-`cyclic-function-indirection'
- `"Symbol's chain of function indirections contains a loop"'
- *Note Function Indirection::.
-
-`domain-error'
- `"Arithmetic domain error"'
-`end-of-buffer'
- `"End of buffer"'
- *Note Motion::.
-
-`end-of-file'
- `"End of file during parsing"'
- This is not a `file-error'.
- *Note Input Functions::.
-
-`file-error'
- This error and its subcategories do not have error-strings,
- because the error message is constructed from the data items alone
- when the error condition `file-error' is present.
- *Note Files::.
-
-`file-locked'
- This is a `file-error'.
- *Note File Locks::.
-
-`file-already-exists'
- This is a `file-error'.
- *Note Writing to Files::.
-
-`file-supersession'
- This is a `file-error'.
- *Note Modification Time::.
-
-`invalid-byte-code'
- `"Invalid byte code"'
- *Note Byte Compilation::.
-
-`invalid-function'
- `"Invalid function"'
- *Note Classifying Lists::.
-
-`invalid-read-syntax'
- `"Invalid read syntax"'
- *Note Input Functions::.
-
-`invalid-regexp'
- `"Invalid regexp"'
- *Note Regular Expressions::.
-
-`mark-inactive'
- `"The mark is not active now"'
-`no-catch'
- `"No catch for tag"'
- *Note Catch and Throw::.
-
-`overflow-error'
- `"Arithmetic overflow error"'
-`protected-field'
- `"Attempt to modify a protected field"'
-`range-error'
- `"Arithmetic range error"'
-`search-failed'
- `"Search failed"'
- *Note Searching and Matching::.
-
-`setting-constant'
- `"Attempt to set a constant symbol"'
- *Note Variables that Never Change: Constant Variables.
-
-`singularity-error'
- `"Arithmetic singularity error"'
-`tooltalk-error'
- `"ToolTalk error"'
- *Note ToolTalk Support::.
-
-`undefined-keystroke-sequence'
- `"Undefined keystroke sequence"'
-`void-function'
- `"Symbol's function definition is void"'
- *Note Function Cells::.
-
-`void-variable'
- `"Symbol's value as variable is void"'
- *Note Accessing Variables::.
-
-`wrong-number-of-arguments'
- `"Wrong number of arguments"'
- *Note Classifying Lists::.
-
-`wrong-type-argument'
- `"Wrong type argument"'
- *Note Type Predicates::.
-
- These error types, which are all classified as special cases of
-`arith-error', can occur on certain systems for invalid use of
-mathematical functions.
-
-`domain-error'
- `"Arithmetic domain error"'
- *Note Math Functions::.
-
-`overflow-error'
- `"Arithmetic overflow error"'
- *Note Math Functions::.
-
-`range-error'
- `"Arithmetic range error"'
- *Note Math Functions::.
-
-`singularity-error'
- `"Arithmetic singularity error"'
- *Note Math Functions::.
-
-`underflow-error'
- `"Arithmetic underflow error"'
- *Note Math Functions::.
-
-\1f
-File: lispref.info, Node: Standard Buffer-Local Variables, Next: Standard Keymaps, Prev: Standard Errors, Up: Top
-
-Buffer-Local Variables
-**********************
-
- The table below lists the general-purpose Emacs variables that are
-automatically local (when set) in each buffer. Many Lisp packages
-define such variables for their internal use; we don't list them here.
-
-`abbrev-mode'
- *note Abbrevs::
-
-`auto-fill-function'
- *note Auto Filling::
-
-`buffer-auto-save-file-name'
- *note Auto-Saving::
-
-`buffer-backed-up'
- *note Backup Files::
-
-`buffer-display-table'
- *note Display Tables::
-
-`buffer-file-format'
- *note Format Conversion::
-
-`buffer-file-name'
- *note Buffer File Name::
-
-`buffer-file-number'
- *note Buffer File Name::
-
-`buffer-file-truename'
- *note Buffer File Name::
-
-`buffer-file-type'
- *note Files and MS-DOS::
-
-`buffer-invisibility-spec'
- *note Invisible Text::
-
-`buffer-offer-save'
- *note Saving Buffers::
-
-`buffer-read-only'
- *note Read Only Buffers::
-
-`buffer-saved-size'
- *note Point::
-
-`buffer-undo-list'
- *note Undo::
-
-`cache-long-line-scans'
- *note Text Lines::
-
-`case-fold-search'
- *note Searching and Case::
-
-`ctl-arrow'
- *note Usual Display::
-
-`comment-column'
- *note Comments: (emacs)Comments.
-
-`default-directory'
- *note System Environment::
-
-`defun-prompt-regexp'
- *note List Motion::
-
-`fill-column'
- *note Auto Filling::
-
-`goal-column'
- *note Moving Point: (emacs)Moving Point.
-
-`left-margin'
- *note Indentation::
-
-`local-abbrev-table'
- *note Abbrevs::
-
-`local-write-file-hooks'
- *note Saving Buffers::
-
-`major-mode'
- *note Mode Help::
+File: lispref.info, Node: MULE Characters, Next: Composite Characters, Prev: Charsets, Up: MULE
-`mark-active'
- *note The Mark::
-
-`mark-ring'
- *note The Mark::
-
-`minor-modes'
- *note Minor Modes::
-
-`modeline-format'
- *note Modeline Data::
-
-`modeline-buffer-identification'
- *note Modeline Variables::
-
-`modeline-format'
- *note Modeline Data::
-
-`modeline-modified'
- *note Modeline Variables::
-
-`modeline-process'
- *note Modeline Variables::
-
-`mode-name'
- *note Modeline Variables::
-
-`overwrite-mode'
- *note Insertion::
-
-`paragraph-separate'
- *note Standard Regexps::
-
-`paragraph-start'
- *note Standard Regexps::
-
-`point-before-scroll'
- Used for communication between mouse commands and scroll-bar
- commands.
-
-`require-final-newline'
- *note Insertion::
+MULE Characters
+===============
-`selective-display'
- *note Selective Display::
+ - Function: make-char charset arg1 &optional arg2
+ This function makes a multi-byte character from CHARSET and octets
+ ARG1 and ARG2.
-`selective-display-ellipses'
- *note Selective Display::
+ - Function: char-charset ch
+ This function returns the character set of char CH.
-`tab-width'
- *note Usual Display::
+ - Function: char-octet ch &optional n
+ This function returns the octet (i.e. position code) numbered N
+ (should be 0 or 1) of char CH. N defaults to 0 if omitted.
-`truncate-lines'
- *note Truncation::
+ - Function: find-charset-region start end &optional buffer
+ This function returns a list of the charsets in the region between
+ START and END. BUFFER defaults to the current buffer if omitted.
-`vc-mode'
- *note Modeline Variables::
+ - Function: find-charset-string string
+ This function returns a list of the charsets in STRING.
\1f
-File: lispref.info, Node: Standard Keymaps, Next: Standard Hooks, Prev: Standard Buffer-Local Variables, Up: Top
-
-Standard Keymaps
-****************
-
- The following symbols are used as the names for various keymaps.
-Some of these exist when XEmacs is first started, others are loaded
-only when their respective mode is used. This is not an exhaustive
-list.
-
- Almost all of these maps are used as local maps. Indeed, of the
-modes that presently exist, only Vip mode and Terminal mode ever change
-the global keymap.
-
-`bookmark-map'
- A keymap containing bindings to bookmark functions.
-
-`Buffer-menu-mode-map'
- A keymap used by Buffer Menu mode.
-
-`c++-mode-map'
- A keymap used by C++ mode.
-
-`c-mode-map'
- A keymap used by C mode. A sparse keymap used by C mode.
-
-`command-history-map'
- A keymap used by Command History mode.
-
-`ctl-x-4-map'
- A keymap for subcommands of the prefix `C-x 4'.
-
-`ctl-x-5-map'
- A keymap for subcommands of the prefix `C-x 5'.
-
-`ctl-x-map'
- A keymap for `C-x' commands.
-
-`debugger-mode-map'
- A keymap used by Debugger mode.
-
-`dired-mode-map'
- A keymap for `dired-mode' buffers.
-
-`edit-abbrevs-map'
- A keymap used in `edit-abbrevs'.
-
-`edit-tab-stops-map'
- A keymap used in `edit-tab-stops'.
-
-`electric-buffer-menu-mode-map'
- A keymap used by Electric Buffer Menu mode.
-
-`electric-history-map'
- A keymap used by Electric Command History mode.
-
-`emacs-lisp-mode-map'
- A keymap used by Emacs Lisp mode.
-
-`help-map'
- A keymap for characters following the Help key.
-
-`Helper-help-map'
- A keymap used by the help utility package.
- It has the same keymap in its value cell and in its function cell.
-
-`Info-edit-map'
- A keymap used by the `e' command of Info.
-
-`Info-mode-map'
- A keymap containing Info commands.
-
-`isearch-mode-map'
- A keymap that defines the characters you can type within
- incremental search.
-
-`itimer-edit-map'
- A keymap used when in Itimer Edit mode.
+File: lispref.info, Node: Composite Characters, Next: Coding Systems, Prev: MULE Characters, Up: MULE
-`lisp-interaction-mode-map'
- A keymap used by Lisp mode.
+Composite Characters
+====================
-`lisp-mode-map'
- A keymap used by Lisp mode.
+ Composite characters are not yet completely implemented.
- A keymap for minibuffer input with completion.
+ - Function: make-composite-char string
+ This function converts a string into a single composite character.
+ The character is the result of overstriking all the characters in
+ the string.
-`minibuffer-local-isearch-map'
- A keymap for editing isearch strings in the minibuffer.
+ - Function: composite-char-string ch
+ This function returns a string of the characters comprising a
+ composite character.
-`minibuffer-local-map'
- Default keymap to use when reading from the minibuffer.
+ - Function: compose-region start end &optional buffer
+ This function composes the characters in the region from START to
+ END in BUFFER into one composite character. The composite
+ character replaces the composed characters. BUFFER defaults to
+ the current buffer if omitted.
-`minibuffer-local-must-match-map'
- A keymap for minibuffer input with completion, for exact match.
-
-`mode-specific-map'
- The keymap for characters following `C-c'. Note, this is in the
- global map. This map is not actually mode specific: its name was
- chosen to be informative for the user in `C-h b'
- (`display-bindings'), where it describes the main use of the `C-c'
- prefix key.
-
-`modeline-map'
- The keymap consulted for mouse-clicks on the modeline of a window.
-
-`objc-mode-map'
- A keymap used in Objective C mode as a local map.
-
-`occur-mode-map'
- A local keymap used by Occur mode.
-
-`overriding-local-map'
- A keymap that overrides all other local keymaps.
-
-`query-replace-map'
- A local keymap used for responses in `query-replace' and related
- commands; also for `y-or-n-p' and `map-y-or-n-p'. The functions
- that use this map do not support prefix keys; they look up one
- event at a time.
-
-`read-expression-map'
- The minibuffer keymap used for reading Lisp expressions.
-
-`read-shell-command-map'
- The minibuffer keymap used by shell-command and related commands.
-
-`shared-lisp-mode-map'
- A keymap for commands shared by all sorts of Lisp modes.
-
-`text-mode-map'
- A keymap used by Text mode.
-
-`toolbar-map'
- The keymap consulted for mouse-clicks over a toolbar.
-
-`view-mode-map'
- A keymap used by View mode.
+ - Function: decompose-region start end &optional buffer
+ This function decomposes any composite characters in the region
+ from START to END in BUFFER. This converts each composite
+ character into one or more characters, the individual characters
+ out of which the composite character was formed. Non-composite
+ characters are left as-is. BUFFER defaults to the current buffer
+ if omitted.
\1f
-File: lispref.info, Node: Standard Hooks, Next: Index, Prev: Standard Keymaps, Up: Top
-
-Standard Hooks
-**************
-
- The following is a list of hook variables that let you provide
-functions to be called from within Emacs on suitable occasions.
-
- Most of these variables have names ending with `-hook'. They are
-"normal hooks", run by means of `run-hooks'. The value of such a hook
-is a list of functions. The recommended way to put a new function on
-such a hook is to call `add-hook'. *Note Hooks::, for more information
-about using hooks.
-
- The variables whose names end in `-function' have single functions
-as their values. Usually there is a specific reason why the variable is
-not a normal hook, such as the need to pass arguments to the function.
-(In older Emacs versions, some of these variables had names ending in
-`-hook' even though they were not normal hooks.)
-
- The variables whose names end in `-hooks' or `-functions' have lists
-of functions as their values, but these functions are called in a
-special way (they are passed arguments, or else their values are used).
-
-`activate-menubar-hook'
-
-`activate-popup-menu-hook'
-
-`ad-definition-hooks'
-
-`adaptive-fill-function'
-
-`add-log-current-defun-function'
-
-`after-change-functions'
-
-`after-delete-annotation-hook'
-
-`after-init-hook'
-
-`after-insert-file-functions'
-
-`after-revert-hook'
-
-`after-save-hook'
-
-`after-set-visited-file-name-hooks'
-
-`after-write-file-hooks'
-
-`auto-fill-function'
-
-`auto-save-hook'
-
-`before-change-functions'
-
-`before-delete-annotation-hook'
-
-`before-init-hook'
-
-`before-revert-hook'
-
-`blink-paren-function'
-
-`buffers-menu-switch-to-buffer-function'
-
-`c++-mode-hook'
-
-`c-delete-function'
-
-`c-mode-common-hook'
-
-`c-mode-hook'
-
-`c-special-indent-hook'
-
-`calendar-load-hook'
-
-`change-major-mode-hook'
-
-`command-history-hook'
-
-`comment-indent-function'
-
-`compilation-buffer-name-function'
-
-`compilation-exit-message-function'
-
-`compilation-finish-function'
-
-`compilation-parse-errors-function'
-
-`compilation-mode-hook'
-
-`create-console-hook'
-
-`create-device-hook'
-
-`create-frame-hook'
-
-`dabbrev-friend-buffer-function'
-
-`dabbrev-select-buffers-function'
-
-`delete-console-hook'
-
-`delete-device-hook'
-
-`delete-frame-hook'
-
-`deselect-frame-hook'
-
-`diary-display-hook'
-
-`diary-hook'
-
-`dired-after-readin-hook'
-
-`dired-before-readin-hook'
-
-`dired-load-hook'
-
-`dired-mode-hook'
-
-`disabled-command-hook'
-
-`display-buffer-function'
-
-`ediff-after-setup-control-frame-hook'
-
-`ediff-after-setup-windows-hook'
-
-`ediff-before-setup-control-frame-hook'
-
-`ediff-before-setup-windows-hook'
-
-`ediff-brief-help-message-function'
-
-`ediff-cleanup-hook'
-
-`ediff-control-frame-position-function'
+File: lispref.info, Node: Coding Systems, Next: CCL, Prev: Composite Characters, Up: MULE
+
+Coding Systems
+==============
+
+ A coding system is an object that defines how text containing
+multiple character sets is encoded into a stream of (typically 8-bit)
+bytes. The coding system is used to decode the stream into a series of
+characters (which may be from multiple charsets) when the text is read
+from a file or process, and is used to encode the text back into the
+same format when it is written out to a file or process.
+
+ For example, many ISO-2022-compliant coding systems (such as Compound
+Text, which is used for inter-client data under the X Window System) use
+escape sequences to switch between different charsets - Japanese Kanji,
+for example, is invoked with `ESC $ ( B'; ASCII is invoked with `ESC (
+B'; and Cyrillic is invoked with `ESC - L'. See `make-coding-system'
+for more information.
+
+ Coding systems are normally identified using a symbol, and the
+symbol is accepted in place of the actual coding system object whenever
+a coding system is called for. (This is similar to how faces and
+charsets work.)
+
+ - Function: coding-system-p object
+ This function returns non-`nil' if OBJECT is a coding system.
+
+* Menu:
+
+* Coding System Types:: Classifying coding systems.
+* ISO 2022:: An international standard for
+ charsets and encodings.
+* EOL Conversion:: Dealing with different ways of denoting
+ the end of a line.
+* Coding System Properties:: Properties of a coding system.
+* Basic Coding System Functions:: Working with coding systems.
+* Coding System Property Functions:: Retrieving a coding system's properties.
+* Encoding and Decoding Text:: Encoding and decoding text.
+* Detection of Textual Encoding:: Determining how text is encoded.
+* Big5 and Shift-JIS Functions:: Special functions for these non-standard
+ encodings.
+* Predefined Coding Systems:: Coding systems implemented by MULE.
-`ediff-display-help-hook'
-
-`ediff-focus-on-regexp-matches-function'
-
-`ediff-forward-word-function'
-
-`ediff-hide-regexp-matches-function'
-
-`ediff-keymap-setup-hook'
-
-`ediff-load-hook'
-
-`ediff-long-help-message-function'
-
-`ediff-make-wide-display-function'
-
-`ediff-merge-split-window-function'
-
-`ediff-meta-action-function'
-
-`ediff-meta-redraw-function'
-
-`ediff-mode-hook'
-
-`ediff-prepare-buffer-hook'
-
-`ediff-quit-hook'
-
-`ediff-registry-setup-hook'
-
-`ediff-select-hook'
-
-`ediff-session-action-function'
-
-`ediff-session-group-setup-hook'
-
-`ediff-setup-diff-regions-function'
-
-`ediff-show-registry-hook'
-
-`ediff-show-session-group-hook'
-
-`ediff-skip-diff-region-function'
-
-`ediff-split-window-function'
-
-`ediff-startup-hook'
-
-`ediff-suspend-hook'
-
-`ediff-toggle-read-only-function'
-
-`ediff-unselect-hook'
-
-`ediff-window-setup-function'
-
-`edit-picture-hook'
-
-`electric-buffer-menu-mode-hook'
-
-`electric-command-history-hook'
-
-`electric-help-mode-hook'
-
-`emacs-lisp-mode-hook'
-
-`fill-paragraph-function'
-
-`find-file-hooks'
-
-`find-file-not-found-hooks'
-
-`first-change-hook'
-
-`font-lock-after-fontify-buffer-hook'
-
-`font-lock-beginning-of-syntax-function'
-
-`font-lock-mode-hook'
-
-`fume-found-function-hook'
-
-`fume-list-mode-hook'
-
-`fume-rescan-buffer-hook'
-
-`fume-sort-function'
-
-`gnus-startup-hook'
-
-`hack-local-variables-hook'
-
-`highlight-headers-follow-url-function'
-
-`hyper-apropos-mode-hook'
-
-`indent-line-function'
-
-`indent-mim-hook'
-
-`indent-region-function'
-
-`initial-calendar-window-hook'
-
-`isearch-mode-end-hook'
-
-`isearch-mode-hook'
-
-`java-mode-hook'
-
-`kill-buffer-hook'
-
-`kill-buffer-query-functions'
-
-`kill-emacs-hook'
-
-`kill-emacs-query-functions'
-
-`kill-hooks'
-
-`LaTeX-mode-hook'
-
-`latex-mode-hook'
-
-`ledit-mode-hook'
-
-`lisp-indent-function'
-
-`lisp-interaction-mode-hook'
-
-`lisp-mode-hook'
-
-`list-diary-entries-hook'
-
-`load-read-function'
-
-`log-message-filter-function'
-
-`m2-mode-hook'
-
-`mail-citation-hook'
-
-`mail-mode-hook'
-
-`mail-setup-hook'
-
-`make-annotation-hook'
-
-`makefile-mode-hook'
-
-`map-frame-hook'
-
-`mark-diary-entries-hook'
-
-`medit-mode-hook'
-
-`menu-no-selection-hook'
-
-`mh-compose-letter-hook'
-
-`mh-folder-mode-hook'
-
-`mh-letter-mode-hook'
-
-`mim-mode-hook'
-
-`minibuffer-exit-hook'
-
-`minibuffer-setup-hook'
-
-`mode-motion-hook'
-
-`mouse-enter-frame-hook'
-
-`mouse-leave-frame-hook'
-
-`mouse-track-cleanup-hook'
-
-`mouse-track-click-hook'
-
-`mouse-track-down-hook'
-
-`mouse-track-drag-hook'
-
-`mouse-track-drag-up-hook'
-
-`mouse-track-up-hook'
-
-`mouse-yank-function'
-
-`news-mode-hook'
-
-`news-reply-mode-hook'
-
-`news-setup-hook'
-
-`nongregorian-diary-listing-hook'
-
-`nongregorian-diary-marking-hook'
-
-`nroff-mode-hook'
-
-`objc-mode-hook'
-
-`outline-mode-hook'
-
-`perl-mode-hook'
-
-`plain-TeX-mode-hook'
-
-`post-command-hook'
-
-`post-gc-hook'
-
-`pre-abbrev-expand-hook'
-
-`pre-command-hook'
-
-`pre-display-buffer-function'
-
-`pre-gc-hook'
-
-`pre-idle-hook'
-
-`print-diary-entries-hook'
-
-`prolog-mode-hook'
-
-`protect-innocence-hook'
-
-`remove-message-hook'
-
-`revert-buffer-function'
-
-`revert-buffer-insert-contents-function'
-
-`rmail-edit-mode-hook'
-
-`rmail-mode-hook'
-
-`rmail-retry-setup-hook'
-
-`rmail-summary-mode-hook'
-
-`scheme-indent-hook'
-
-`scheme-mode-hook'
-
-`scribe-mode-hook'
-
-`select-frame-hook'
-
-`send-mail-function'
-
-`shell-mode-hook'
-
-`shell-set-directory-error-hook'
-
-`special-display-function'
-
-`suspend-hook'
-
-`suspend-resume-hook'
-
-`temp-buffer-show-function'
-
-`term-setup-hook'
-
-`terminal-mode-hook'
-
-`terminal-mode-break-hook'
-
-`TeX-mode-hook'
-
-`tex-mode-hook'
-
-`text-mode-hook'
-
-`today-visible-calendar-hook'
-
-`today-invisible-calendar-hook'
-
-`tooltalk-message-handler-hook'
-
-`tooltalk-pattern-handler-hook'
+\1f
+File: lispref.info, Node: Coding System Types, Next: ISO 2022, Up: Coding Systems
+
+Coding System Types
+-------------------
+
+ The coding system type determines the basic algorithm XEmacs will
+use to decode or encode a data stream. Character encodings will be
+converted to the MULE encoding, escape sequences processed, and newline
+sequences converted to XEmacs's internal representation. There are
+three basic classes of coding system type: no-conversion, ISO-2022, and
+special.
+
+ No conversion allows you to look at the file's internal
+representation. Since XEmacs is basically a text editor, "no
+conversion" does convert newline conventions by default. (Use the
+'binary coding-system if this is not desired.)
+
+ ISO 2022 (*note ISO 2022::) is the basic international standard
+regulating use of "coded character sets for the exchange of data", ie,
+text streams. ISO 2022 contains functions that make it possible to
+encode text streams to comply with restrictions of the Internet mail
+system and de facto restrictions of most file systems (eg, use of the
+separator character in file names). Coding systems which are not ISO
+2022 conformant can be difficult to handle. Perhaps more important,
+they are not adaptable to multilingual information interchange, with
+the obvious exception of ISO 10646 (Unicode). (Unicode is partially
+supported by XEmacs with the addition of the Lisp package ucs-conv.)
+
+ The special class of coding systems includes automatic detection,
+CCL (a "little language" embedded as an interpreter, useful for
+translating between variants of a single character set),
+non-ISO-2022-conformant encodings like Unicode, Shift JIS, and Big5,
+and MULE internal coding. (NB: this list is based on XEmacs 21.2.
+Terminology may vary slightly for other versions of XEmacs and for GNU
+Emacs 20.)
+
+`no-conversion'
+ No conversion, for binary files, and a few special cases of
+ non-ISO-2022 coding systems where conversion is done by hook
+ functions (usually implemented in CCL). On output, graphic
+ characters that are not in ASCII or Latin-1 will be replaced by a
+ `?'. (For a no-conversion-encoded buffer, these characters will
+ only be present if you explicitly insert them.)
+
+`iso2022'
+ Any ISO-2022-compliant encoding. Among others, this includes JIS
+ (the Japanese encoding commonly used for e-mail), national
+ variants of EUC (the standard Unix encoding for Japanese and other
+ languages), and Compound Text (an encoding used in X11). You can
+ specify more specific information about the conversion with the
+ FLAGS argument.
+
+`ucs-4'
+ ISO 10646 UCS-4 encoding. A 31-bit fixed-width superset of
+ Unicode.
+
+`utf-8'
+ ISO 10646 UTF-8 encoding. A "file system safe" transformation
+ format that can be used with both UCS-4 and Unicode.
+
+`undecided'
+ Automatic conversion. XEmacs attempts to detect the coding system
+ used in the file.
+
+`shift-jis'
+ Shift-JIS (a Japanese encoding commonly used in PC operating
+ systems).
+
+`big5'
+ Big5 (the encoding commonly used for Taiwanese).
+
+`ccl'
+ The conversion is performed using a user-written pseudo-code
+ program. CCL (Code Conversion Language) is the name of this
+ pseudo-code. For example, CCL is used to map KOI8-R characters
+ (an encoding for Russian Cyrillic) to ISO8859-5 (the form used
+ internally by MULE).
+
+`internal'
+ Write out or read in the raw contents of the memory representing
+ the buffer's text. This is primarily useful for debugging
+ purposes, and is only enabled when XEmacs has been compiled with
+ `DEBUG_XEMACS' set (the `--debug' configure option). *Warning*:
+ Reading in a file using `internal' conversion can result in an
+ internal inconsistency in the memory representing a buffer's text,
+ which will produce unpredictable results and may cause XEmacs to
+ crash. Under normal circumstances you should never use `internal'
+ conversion.
-`tooltalk-unprocessed-message-hook'
+\1f
+File: lispref.info, Node: ISO 2022, Next: EOL Conversion, Prev: Coding System Types, Up: Coding Systems
+
+ISO 2022
+========
+
+ This section briefly describes the ISO 2022 encoding standard. A
+more thorough treatment is available in the original document of ISO
+2022 as well as various national standards (such as JIS X 0202).
+
+ Character sets ("charsets") are classified into the following four
+categories, according to the number of characters in the charset:
+94-charset, 96-charset, 94x94-charset, and 96x96-charset. This means
+that although an ISO 2022 coding system may have variable width
+characters, each charset used is fixed-width (in contrast to the MULE
+character set and UTF-8, for example).
+
+ ISO 2022 provides for switching between character sets via escape
+sequences. This switching is somewhat complicated, because ISO 2022
+provides for both legacy applications like Internet mail that accept
+only 7 significant bits in some contexts (RFC 822 headers, for example),
+and more modern "8-bit clean" applications. It also provides for
+compact and transparent representation of languages like Japanese which
+mix ASCII and a national script (even outside of computer programs).
+
+ First, ISO 2022 codified prevailing practice by dividing the code
+space into "control" and "graphic" regions. The code points 0x00-0x1F
+and 0x80-0x9F are reserved for "control characters", while "graphic
+characters" must be assigned to code points in the regions 0x20-0x7F and
+0xA0-0xFF. The positions 0x20 and 0x7F are special, and under some
+circumstances must be assigned the graphic character "ASCII SPACE" and
+the control character "ASCII DEL" respectively.
+
+ The various regions are given the name C0 (0x00-0x1F), GL
+(0x20-0x7F), C1 (0x80-0x9F), and GR (0xA0-0xFF). GL and GR stand for
+"graphic left" and "graphic right", respectively, because of the
+standard method of displaying graphic character sets in tables with the
+high byte indexing columns and the low byte indexing rows. I don't
+find it very intuitive, but these are called "registers".
+
+ An ISO 2022-conformant encoding for a graphic character set must use
+a fixed number of bytes per character, and the values must fit into a
+single register; that is, each byte must range over either 0x20-0x7F, or
+0xA0-0xFF. It is not allowed to extend the range of the repertoire of a
+character set by using both ranges at the same. This is why a standard
+character set such as ISO 8859-1 is actually considered by ISO 2022 to
+be an aggregation of two character sets, ASCII and LATIN-1, and why it
+is technically incorrect to refer to ISO 8859-1 as "Latin 1". Also, a
+single character's bytes must all be drawn from the same register; this
+is why Shift JIS (for Japanese) and Big 5 (for Chinese) are not ISO
+2022-compatible encodings.
+
+ The reason for this restriction becomes clear when you attempt to
+define an efficient, robust encoding for a language like Japanese.
+Like ISO 8859, Japanese encodings are aggregations of several character
+sets. In practice, the vast majority of characters are drawn from the
+"JIS Roman" character set (a derivative of ASCII; it won't hurt to
+think of it as ASCII) and the JIS X 0208 standard "basic Japanese"
+character set including not only ideographic characters ("kanji") but
+syllabic Japanese characters ("kana"), a wide variety of symbols, and
+many alphabetic characters (Roman, Greek, and Cyrillic) as well.
+Although JIS X 0208 includes the whole Roman alphabet, as a 2-byte code
+it is not suited to programming; thus the inclusion of ASCII in the
+standard Japanese encodings.
+
+ For normal Japanese text such as in newspapers, a broad repertoire of
+approximately 3000 characters is used. Evidently this won't fit into
+one byte; two must be used. But much of the text processed by Japanese
+computers is computer source code, nearly all of which is ASCII. A not
+insignificant portion of ordinary text is English (as such or as
+borrowed Japanese vocabulary) or other languages which can represented
+at least approximately in ASCII, as well. It seems reasonable then to
+represent ASCII in one byte, and JIS X 0208 in two. And this is exactly
+what the Extended Unix Code for Japanese (EUC-JP) does. ASCII is
+invoked to the GL register, and JIS X 0208 is invoked to the GR
+register. Thus, each byte can be tested for its character set by
+looking at the high bit; if set, it is Japanese, if clear, it is ASCII.
+Furthermore, since control characters like newline can never be part of
+a graphic character, even in the case of corruption in transmission the
+stream will be resynchronized at every line break, on the order of 60-80
+bytes. This coding system requires no escape sequences or special
+control codes to represent 99.9% of all Japanese text.
+
+ Note carefully the distinction between the character sets (ASCII and
+JIS X 0208), the encoding (EUC-JP), and the coding system (ISO 2022).
+The JIS X 0208 character set is used in three different encodings for
+Japanese, but in ISO-2022-JP it is invoked into GL (so the high bit is
+always clear), in EUC-JP it is invoked into GR (setting the high bit in
+the process), and in Shift JIS the high bit may be set or reset, and the
+significant bits are shifted within the 16-bit character so that the two
+main character sets can coexist with a third (the "halfwidth katakana"
+of JIS X 0201). As the name implies, the ISO-2022-JP encoding is also a
+version of the ISO-2022 coding system.
+
+ In order to systematically treat subsidiary character sets (like the
+"halfwidth katakana" already mentioned, and the "supplementary kanji" of
+JIS X 0212), four further registers are defined: G0, G1, G2, and G3.
+Unlike GL and GR, they are not logically distinguished by internal
+format. Instead, the process of "invocation" mentioned earlier is
+broken into two steps: first, a character set is "designated" to one of
+the registers G0-G3 by use of an "escape sequence" of the form:
+
+ ESC [I] I F
+
+ where I is an intermediate character or characters in the range 0x20
+- 0x3F, and F, from the range 0x30-0x7Fm is the final character
+identifying this charset. (Final characters in the range 0x30-0x3F are
+reserved for private use and will never have a publically registered
+meaning.)
+
+ Then that register is "invoked" to either GL or GR, either
+automatically (designations to G0 normally involve invocation to GL as
+well), or by use of shifting (affecting only the following character in
+the data stream) or locking (effective until the next designation or
+locking) control sequences. An encoding conformant to ISO 2022 is
+typically defined by designating the initial contents of the G0-G3
+registers, specifying an 7 or 8 bit environment, and specifying whether
+further designations will be recognized.
+
+ Some examples of character sets and the registered final characters
+F used to designate them:
+
+94-charset
+ ASCII (B), left (J) and right (I) half of JIS X 0201, ...
+
+96-charset
+ Latin-1 (A), Latin-2 (B), Latin-3 (C), ...
+
+94x94-charset
+ GB2312 (A), JIS X 0208 (B), KSC5601 (C), ...
+
+96x96-charset
+ none for the moment
+
+ The meanings of the various characters in these sequences, where not
+specified by the ISO 2022 standard (such as the ESC character), are
+assigned by "ECMA", the European Computer Manufacturers Association.
+
+ The meaning of intermediate characters are:
+
+ $ [0x24]: indicate charset of dimension 2 (94x94 or 96x96).
+ ( [0x28]: designate to G0 a 94-charset whose final byte is F.
+ ) [0x29]: designate to G1 a 94-charset whose final byte is F.
+ * [0x2A]: designate to G2 a 94-charset whose final byte is F.
+ + [0x2B]: designate to G3 a 94-charset whose final byte is F.
+ , [0x2C]: designate to G0 a 96-charset whose final byte is F.
+ - [0x2D]: designate to G1 a 96-charset whose final byte is F.
+ . [0x2E]: designate to G2 a 96-charset whose final byte is F.
+ / [0x2F]: designate to G3 a 96-charset whose final byte is F.
+
+ The comma may be used in files read and written only by MULE, as a
+MULE extension, but this is illegal in ISO 2022. (The reason is that
+in ISO 2022 G0 must be a 94-member character set, with 0x20 assigned
+the value SPACE, and 0x7F assigned the value DEL.)
+
+ Here are examples of designations:
+
+ ESC ( B : designate to G0 ASCII
+ ESC - A : designate to G1 Latin-1
+ ESC $ ( A or ESC $ A : designate to G0 GB2312
+ ESC $ ( B or ESC $ B : designate to G0 JISX0208
+ ESC $ ) C : designate to G1 KSC5601
+
+ (The short forms used to designate GB2312 and JIS X 0208 are for
+backwards compatibility; the long forms are preferred.)
+
+ To use a charset designated to G2 or G3, and to use a charset
+designated to G1 in a 7-bit environment, you must explicitly invoke G1,
+G2, or G3 into GL. There are two types of invocation, Locking Shift
+(forever) and Single Shift (one character only).
+
+ Locking Shift is done as follows:
+
+ LS0 or SI (0x0F): invoke G0 into GL
+ LS1 or SO (0x0E): invoke G1 into GL
+ LS2: invoke G2 into GL
+ LS3: invoke G3 into GL
+ LS1R: invoke G1 into GR
+ LS2R: invoke G2 into GR
+ LS3R: invoke G3 into GR
+
+ Single Shift is done as follows:
+
+ SS2 or ESC N: invoke G2 into GL
+ SS3 or ESC O: invoke G3 into GL
+
+ The shift functions (such as LS1R and SS3) are represented by control
+characters (from C1) in 8 bit environments and by escape sequences in 7
+bit environments.
+
+ (#### Ben says: I think the above is slightly incorrect. It appears
+that SS2 invokes G2 into GR and SS3 invokes G3 into GR, whereas ESC N
+and ESC O behave as indicated. The above definitions will not parse
+EUC-encoded text correctly, and it looks like the code in mule-coding.c
+has similar problems.)
+
+ Evidently there are a lot of ISO-2022-compliant ways of encoding
+multilingual text. Now, in the world, there exist many coding systems
+such as X11's Compound Text, Japanese JUNET code, and so-called EUC
+(Extended UNIX Code); all of these are variants of ISO 2022.
+
+ In MULE, we characterize a version of ISO 2022 by the following
+attributes:
+
+ 1. The character sets initially designated to G0 thru G3.
+
+ 2. Whether short form designations are allowed for Japanese and
+ Chinese.
+
+ 3. Whether ASCII should be designated to G0 before control characters.
+
+ 4. Whether ASCII should be designated to G0 at the end of line.
+
+ 5. 7-bit environment or 8-bit environment.
+
+ 6. Whether Locking Shifts are used or not.
+
+ 7. Whether to use ASCII or the variant JIS X 0201-1976-Roman.
+
+ 8. Whether to use JIS X 0208-1983 or the older version JIS X
+ 0208-1976.
+
+ (The last two are only for Japanese.)
+
+ By specifying these attributes, you can create any variant of ISO
+2022.
+
+ Here are several examples:
+
+ ISO-2022-JP -- Coding system used in Japanese email (RFC 1463 #### check).
+ 1. G0 <- ASCII, G1..3 <- never used
+ 2. Yes.
+ 3. Yes.
+ 4. Yes.
+ 5. 7-bit environment
+ 6. No.
+ 7. Use ASCII
+ 8. Use JIS X 0208-1983
+
+ ctext -- X11 Compound Text
+ 1. G0 <- ASCII, G1 <- Latin-1, G2,3 <- never used.
+ 2. No.
+ 3. No.
+ 4. Yes.
+ 5. 8-bit environment.
+ 6. No.
+ 7. Use ASCII.
+ 8. Use JIS X 0208-1983.
+
+ euc-china -- Chinese EUC. Often called the "GB encoding", but that is
+ technically incorrect.
+ 1. G0 <- ASCII, G1 <- GB 2312, G2,3 <- never used.
+ 2. No.
+ 3. Yes.
+ 4. Yes.
+ 5. 8-bit environment.
+ 6. No.
+ 7. Use ASCII.
+ 8. Use JIS X 0208-1983.
+
+ ISO-2022-KR -- Coding system used in Korean email.
+ 1. G0 <- ASCII, G1 <- KSC 5601, G2,3 <- never used.
+ 2. No.
+ 3. Yes.
+ 4. Yes.
+ 5. 7-bit environment.
+ 6. Yes.
+ 7. Use ASCII.
+ 8. Use JIS X 0208-1983.
+
+ MULE creates all of these coding systems by default.
-`unmap-frame-hook'
+\1f
+File: lispref.info, Node: EOL Conversion, Next: Coding System Properties, Prev: ISO 2022, Up: Coding Systems
-`vc-checkin-hook'
+EOL Conversion
+--------------
-`vc-checkout-writable-buffer-hook'
+`nil'
+ Automatically detect the end-of-line type (LF, CRLF, or CR). Also
+ generate subsidiary coding systems named `NAME-unix', `NAME-dos',
+ and `NAME-mac', that are identical to this coding system but have
+ an EOL-TYPE value of `lf', `crlf', and `cr', respectively.
-`vc-log-after-operation-hook'
+`lf'
+ The end of a line is marked externally using ASCII LF. Since this
+ is also the way that XEmacs represents an end-of-line internally,
+ specifying this option results in no end-of-line conversion. This
+ is the standard format for Unix text files.
-`vc-make-buffer-writable-hook'
+`crlf'
+ The end of a line is marked externally using ASCII CRLF. This is
+ the standard format for MS-DOS text files.
-`view-hook'
+`cr'
+ The end of a line is marked externally using ASCII CR. This is the
+ standard format for Macintosh text files.
-`vm-arrived-message-hook'
+`t'
+ Automatically detect the end-of-line type but do not generate
+ subsidiary coding systems. (This value is converted to `nil' when
+ stored internally, and `coding-system-property' will return `nil'.)
-`vm-arrived-messages-hook'
+\1f
+File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems
+
+Coding System Properties
+------------------------
+
+`mnemonic'
+ String to be displayed in the modeline when this coding system is
+ active.
+
+`eol-type'
+ End-of-line conversion to be used. It should be one of the types
+ listed in *Note EOL Conversion::.
+
+`eol-lf'
+ The coding system which is the same as this one, except that it
+ uses the Unix line-breaking convention.
+
+`eol-crlf'
+ The coding system which is the same as this one, except that it
+ uses the DOS line-breaking convention.
+
+`eol-cr'
+ The coding system which is the same as this one, except that it
+ uses the Macintosh line-breaking convention.
+
+`post-read-conversion'
+ Function called after a file has been read in, to perform the
+ decoding. Called with two arguments, BEG and END, denoting a
+ region of the current buffer to be decoded.
+
+`pre-write-conversion'
+ Function called before a file is written out, to perform the
+ encoding. Called with two arguments, BEG and END, denoting a
+ region of the current buffer to be encoded.
+
+ The following additional properties are recognized if TYPE is
+`iso2022':
+
+`charset-g0'
+`charset-g1'
+`charset-g2'
+`charset-g3'
+ The character set initially designated to the G0 - G3 registers.
+ The value should be one of
+
+ * A charset object (designate that character set)
+
+ * `nil' (do not ever use this register)
+
+ * `t' (no character set is initially designated to the
+ register, but may be later on; this automatically sets the
+ corresponding `force-g*-on-output' property)
+
+`force-g0-on-output'
+`force-g1-on-output'
+`force-g2-on-output'
+`force-g3-on-output'
+ If non-`nil', send an explicit designation sequence on output
+ before using the specified register.
+
+`short'
+ If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $
+ B' on output in place of the full designation sequences `ESC $ (
+ @', `ESC $ ( A', and `ESC $ ( B'.
+
+`no-ascii-eol'
+ If non-`nil', don't designate ASCII to G0 at each end of line on
+ output. Setting this to non-`nil' also suppresses other
+ state-resetting that normally happens at the end of a line.
+
+`no-ascii-cntl'
+ If non-`nil', don't designate ASCII to G0 before control chars on
+ output.
+
+`seven'
+ If non-`nil', use 7-bit environment on output. Otherwise, use
+ 8-bit environment.
+
+`lock-shift'
+ If non-`nil', use locking-shift (SO/SI) instead of single-shift or
+ designation by escape sequence.
+
+`no-iso6429'
+ If non-`nil', don't use ISO6429's direction specification.
+
+`escape-quoted'
+ If non-nil, literal control characters that are the same as the
+ beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in
+ particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3
+ (0x8F), and CSI (0x9B)) are "quoted" with an escape character so
+ that they can be properly distinguished from an escape sequence.
+ (Note that doing this results in a non-portable encoding.) This
+ encoding flag is used for byte-compiled files. Note that ESC is a
+ good choice for a quoting character because there are no escape
+ sequences whose second byte is a character from the Control-0 or
+ Control-1 character sets; this is explicitly disallowed by the ISO
+ 2022 standard.
+
+`input-charset-conversion'
+ A list of conversion specifications, specifying conversion of
+ characters in one charset to another when decoding is performed.
+ Each specification is a list of two elements: the source charset,
+ and the destination charset.
+
+`output-charset-conversion'
+ A list of conversion specifications, specifying conversion of
+ characters in one charset to another when encoding is performed.
+ The form of each specification is the same as for
+ `input-charset-conversion'.
+
+ The following additional properties are recognized (and required) if
+TYPE is `ccl':
+
+`decode'
+ CCL program used for decoding (converting to internal format).
+
+`encode'
+ CCL program used for encoding (converting to external format).
+
+ The following properties are used internally: EOL-CR, EOL-CRLF,
+EOL-LF, and BASE.
-`vm-chop-full-name-function'
+\1f
+File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems
-`vm-display-buffer-hook'
+Basic Coding System Functions
+-----------------------------
-`vm-edit-message-hook'
+ - Function: find-coding-system coding-system-or-name
+ This function retrieves the coding system of the given name.
-`vm-forward-message-hook'
+ If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply
+ returned. Otherwise, CODING-SYSTEM-OR-NAME should be a symbol.
+ If there is no such coding system, `nil' is returned. Otherwise
+ the associated coding system object is returned.
-`vm-iconify-frame-hook'
+ - Function: get-coding-system name
+ This function retrieves the coding system of the given name. Same
+ as `find-coding-system' except an error is signalled if there is no
+ such coding system instead of returning `nil'.
-`vm-inhibit-write-file-hook'
+ - Function: coding-system-list
+ This function returns a list of the names of all defined coding
+ systems.
-`vm-key-functions'
+ - Function: coding-system-name coding-system
+ This function returns the name of the given coding system.
-`vm-mail-hook'
+ - Function: coding-system-base coding-system
+ Returns the base coding system (undecided EOL convention) coding
+ system.
-`vm-mail-mode-hook'
+ - Function: make-coding-system name type &optional doc-string props
+ This function registers symbol NAME as a coding system.
-`vm-menu-setup-hook'
+ TYPE describes the conversion method used and should be one of the
+ types listed in *Note Coding System Types::.
-`vm-mode-hook'
+ DOC-STRING is a string describing the coding system.
-`vm-quit-hook'
+ PROPS is a property list, describing the specific nature of the
+ character set. Recognized properties are as in *Note Coding
+ System Properties::.
-`vm-rename-current-buffer-function'
+ - Function: copy-coding-system old-coding-system new-name
+ This function copies OLD-CODING-SYSTEM to NEW-NAME. If NEW-NAME
+ does not name an existing coding system, a new one will be created.
-`vm-reply-hook'
+ - Function: subsidiary-coding-system coding-system eol-type
+ This function returns the subsidiary coding system of
+ CODING-SYSTEM with eol type EOL-TYPE.
-`vm-resend-bounced-message-hook'
+\1f
+File: lispref.info, Node: Coding System Property Functions, Next: Encoding and Decoding Text, Prev: Basic Coding System Functions, Up: Coding Systems
-`vm-resend-message-hook'
+Coding System Property Functions
+--------------------------------
-`vm-retrieved-spooled-mail-hook'
+ - Function: coding-system-doc-string coding-system
+ This function returns the doc string for CODING-SYSTEM.
-`vm-select-message-hook'
+ - Function: coding-system-type coding-system
+ This function returns the type of CODING-SYSTEM.
-`vm-select-new-message-hook'
+ - Function: coding-system-property coding-system prop
+ This function returns the PROP property of CODING-SYSTEM.
-`vm-select-unread-message-hook'
+\1f
+File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textual Encoding, Prev: Coding System Property Functions, Up: Coding Systems
+
+Encoding and Decoding Text
+--------------------------
+
+ - Function: decode-coding-region start end coding-system &optional
+ buffer
+ This function decodes the text between START and END which is
+ encoded in CODING-SYSTEM. This is useful if you've read in
+ encoded text from a file without decoding it (e.g. you read in a
+ JIS-formatted file but used the `binary' or `no-conversion' coding
+ system, so that it shows up as `^[$B!<!+^[(B'). The length of the
+ encoded text is returned. BUFFER defaults to the current buffer
+ if unspecified.
+
+ - Function: encode-coding-region start end coding-system &optional
+ buffer
+ This function encodes the text between START and END using
+ CODING-SYSTEM. This will, for example, convert Japanese
+ characters into stuff such as `^[$B!<!+^[(B' if you use the JIS
+ encoding. The length of the encoded text is returned. BUFFER
+ defaults to the current buffer if unspecified.
-`vm-send-digest-hook'
+\1f
+File: lispref.info, Node: Detection of Textual Encoding, Next: Big5 and Shift-JIS Functions, Prev: Encoding and Decoding Text, Up: Coding Systems
-`vm-summary-mode-hook'
+Detection of Textual Encoding
+-----------------------------
-`vm-summary-pointer-update-hook'
+ - Function: coding-category-list
+ This function returns a list of all recognized coding categories.
-`vm-summary-redo-hook'
+ - Function: set-coding-priority-list list
+ This function changes the priority order of the coding categories.
+ LIST should be a list of coding categories, in descending order of
+ priority. Unspecified coding categories will be lower in priority
+ than all specified ones, in the same relative order they were in
+ previously.
-`vm-summary-update-hook'
+ - Function: coding-priority-list
+ This function returns a list of coding categories in descending
+ order of priority.
-`vm-undisplay-buffer-hook'
+ - Function: set-coding-category-system coding-category coding-system
+ This function changes the coding system associated with a coding
+ category.
-`vm-visit-folder-hook'
+ - Function: coding-category-system coding-category
+ This function returns the coding system associated with a coding
+ category.
-`window-setup-hook'
+ - Function: detect-coding-region start end &optional buffer
+ This function detects coding system of the text in the region
+ between START and END. Returned value is a list of possible coding
+ systems ordered by priority. If only ASCII characters are found,
+ it returns `autodetect' or one of its subsidiary coding systems
+ according to a detected end-of-line type. Optional arg BUFFER
+ defaults to the current buffer.
-`write-contents-hooks'
+\1f
+File: lispref.info, Node: Big5 and Shift-JIS Functions, Next: Predefined Coding Systems, Prev: Detection of Textual Encoding, Up: Coding Systems
-`write-file-data-hooks'
+Big5 and Shift-JIS Functions
+----------------------------
-`write-file-hooks'
+ These are special functions for working with the non-standard
+Shift-JIS and Big5 encodings.
-`write-region-annotate-functions'
+ - Function: decode-shift-jis-char code
+ This function decodes a JIS X 0208 character of Shift-JIS
+ coding-system. CODE is the character code in Shift-JIS as a cons
+ of type bytes. The corresponding character is returned.
-`x-lost-selection-hooks'
+ - Function: encode-shift-jis-char ch
+ This function encodes a JIS X 0208 character CH to SHIFT-JIS
+ coding-system. The corresponding character code in SHIFT-JIS is
+ returned as a cons of two bytes.
-`x-sent-selection-hooks'
+ - Function: decode-big5-char code
+ This function decodes a Big5 character CODE of BIG5 coding-system.
+ CODE is the character code in BIG5. The corresponding character
+ is returned.
-`zmacs-activate-region-hook'
+ - Function: encode-big5-char ch
+ This function encodes the Big5 character CHAR to BIG5
+ coding-system. The corresponding character code in Big5 is
+ returned.
-`zmacs-deactivate-region-hook'
+\1f
+File: lispref.info, Node: Predefined Coding Systems, Prev: Big5 and Shift-JIS Functions, Up: Coding Systems
+
+Coding Systems Implemented
+--------------------------
+
+ MULE initializes most of the commonly used coding systems at XEmacs's
+startup. A few others are initialized only when the relevant language
+environment is selected and support libraries are loaded. (NB: The
+following list is based on XEmacs 21.2.19, the development branch at the
+time of writing. The list may be somewhat different for other
+versions. Recent versions of GNU Emacs 20 implement a few more rare
+coding systems; work is being done to port these to XEmacs.)
+
+ Unfortunately, there is not a consistent naming convention for
+character sets, and for practical purposes coding systems often take
+their name from their principal character sets (ASCII, KOI8-R, Shift
+JIS). Others take their names from the coding system (ISO-2022-JP,
+EUC-KR), and a few from their non-text usages (internal, binary). To
+provide for this, and for the fact that many coding systems have
+several common names, an aliasing system is provided. Finally, some
+effort has been made to use names that are registered as MIME charsets
+(this is why the name 'shift_jis contains that un-Lisp-y underscore).
+
+ There is a systematic naming convention regarding end-of-line (EOL)
+conventions for different systems. A coding system whose name ends in
+"-unix" forces the assumptions that lines are broken by newlines (0x0A).
+A coding system whose name ends in "-mac" forces the assumptions that
+lines are broken by ASCII CRs (0x0D). A coding system whose name ends
+in "-dos" forces the assumptions that lines are broken by CRLF sequences
+(0x0D 0x0A). These subsidiary coding systems are automatically derived
+from a base coding system. Use of the base coding system implies
+autodetection of the text file convention. (The fact that the -unix,
+-mac, and -dos are derived from a base system results in them showing up
+as "aliases" in `list-coding-systems'.) These subsidiaries have a
+consistent modeline indicator as well. "-dos" coding systems have ":T"
+appended to their modeline indicator, while "-mac" coding systems have
+":t" appended (eg, "ISO8:t" for iso-2022-8-mac).
+
+ In the following table, each coding system is given with its mode
+line indicator in parentheses. Non-textual coding systems are listed
+first, followed by textual coding systems and their aliases. (The
+coding system subsidiary modeline indicators ":T" and ":t" will be
+omitted from the table of coding systems.)
+
+ ### SJT 1999-08-23 Maybe should order these by language? Definitely
+need language usage for the ISO-8859 family.
+
+ Note that although true coding system aliases have been implemented
+for XEmacs 21.2, the coding system initialization has not yet been
+converted as of 21.2.19. So coding systems described as aliases have
+the same properties as the aliased coding system, but will not be equal
+as Lisp objects.
+
+`automatic-conversion'
+`undecided'
+`undecided-dos'
+`undecided-mac'
+`undecided-unix'
+ Modeline indicator: `Auto'. A type `undecided' coding system.
+ Attempts to determine an appropriate coding system from file
+ contents or the environment.
+
+`raw-text'
+`no-conversion'
+`raw-text-dos'
+`raw-text-mac'
+`raw-text-unix'
+`no-conversion-dos'
+`no-conversion-mac'
+`no-conversion-unix'
+ Modeline indicator: `Raw'. A type `no-conversion' coding system,
+ which converts only line-break-codes. An implementation quirk
+ means that this coding system is also used for ISO8859-1.
+
+`binary'
+ Modeline indicator: `Binary'. A type `no-conversion' coding
+ system which does no character coding or EOL conversions. An
+ alias for `raw-text-unix'.
+
+`alternativnyj'
+`alternativnyj-dos'
+`alternativnyj-mac'
+`alternativnyj-unix'
+ Modeline indicator: `Cy.Alt'. A type `ccl' coding system used for
+ Alternativnyj, an encoding of the Cyrillic alphabet.
+
+`big5'
+`big5-dos'
+`big5-mac'
+`big5-unix'
+ Modeline indicator: `Zh/Big5'. A type `big5' coding system used
+ for BIG5, the most common encoding of traditional Chinese as used
+ in Taiwan.
+
+`cn-gb-2312'
+`cn-gb-2312-dos'
+`cn-gb-2312-mac'
+`cn-gb-2312-unix'
+ Modeline indicator: `Zh-GB/EUC'. A type `iso2022' coding system
+ used for simplified Chinese (as used in the People's Republic of
+ China), with the `ascii' (G0), `chinese-gb2312' (G1), and `sisheng'
+ (G2) character sets initially designated. Chinese EUC (Extended
+ Unix Code).
+
+`ctext-hebrew'
+`ctext-hebrew-dos'
+`ctext-hebrew-mac'
+`ctext-hebrew-unix'
+ Modeline indicator: `CText/Hbrw'. A type `iso2022' coding system
+ with the `ascii' (G0) and `hebrew-iso8859-8' (G1) character sets
+ initially designated for Hebrew.
+
+`ctext'
+`ctext-dos'
+`ctext-mac'
+`ctext-unix'
+ Modeline indicator: `CText'. A type `iso2022' 8-bit coding system
+ with the `ascii' (G0) and `latin-iso8859-1' (G1) character sets
+ initially designated. X11 Compound Text Encoding. Often
+ mistakenly recognized instead of EUC encodings; usual cause is
+ inappropriate setting of `coding-priority-list'.
+
+`escape-quoted'
+ Modeline indicator: `ESC/Quot'. A type `iso2022' 8-bit coding
+ system with the `ascii' (G0) and `latin-iso8859-1' (G1) character
+ sets initially designated and escape quoting. Unix EOL conversion
+ (ie, no conversion). It is used for .ELC files.
+
+`euc-jp'
+`euc-jp-dos'
+`euc-jp-mac'
+`euc-jp-unix'
+ Modeline indicator: `Ja/EUC'. A type `iso2022' 8-bit coding system
+ with `ascii' (G0), `japanese-jisx0208' (G1), `katakana-jisx0201'
+ (G2), and `japanese-jisx0212' (G3) initially designated. Japanese
+ EUC (Extended Unix Code).
+
+`euc-kr'
+`euc-kr-dos'
+`euc-kr-mac'
+`euc-kr-unix'
+ Modeline indicator: `ko/EUC'. A type `iso2022' 8-bit coding system
+ with `ascii' (G0) and `korean-ksc5601' (G1) initially designated.
+ Korean EUC (Extended Unix Code).
+
+`hz-gb-2312'
+ Modeline indicator: `Zh-GB/Hz'. A type `no-conversion' coding
+ system with Unix EOL convention (ie, no conversion) using
+ post-read-decode and pre-write-encode functions to translate the
+ Hz/ZW coding system used for Chinese.
+
+`iso-2022-7bit'
+`iso-2022-7bit-unix'
+`iso-2022-7bit-dos'
+`iso-2022-7bit-mac'
+`iso-2022-7'
+ Modeline indicator: `ISO7'. A type `iso2022' 7-bit coding system
+ with `ascii' (G0) initially designated. Other character sets must
+ be explicitly designated to be used.
+
+`iso-2022-7bit-ss2'
+`iso-2022-7bit-ss2-dos'
+`iso-2022-7bit-ss2-mac'
+`iso-2022-7bit-ss2-unix'
+ Modeline indicator: `ISO7/SS'. A type `iso2022' 7-bit coding
+ system with `ascii' (G0) initially designated. Other character
+ sets must be explicitly designated to be used. SS2 is used to
+ invoke a 96-charset, one character at a time.
+
+`iso-2022-8'
+`iso-2022-8-dos'
+`iso-2022-8-mac'
+`iso-2022-8-unix'
+ Modeline indicator: `ISO8'. A type `iso2022' 8-bit coding system
+ with `ascii' (G0) and `latin-iso8859-1' (G1) initially designated.
+ Other character sets must be explicitly designated to be used.
+ No single-shift or locking-shift.
+
+`iso-2022-8bit-ss2'
+`iso-2022-8bit-ss2-dos'
+`iso-2022-8bit-ss2-mac'
+`iso-2022-8bit-ss2-unix'
+ Modeline indicator: `ISO8/SS'. A type `iso2022' 8-bit coding
+ system with `ascii' (G0) and `latin-iso8859-1' (G1) initially
+ designated. Other character sets must be explicitly designated to
+ be used. SS2 is used to invoke a 96-charset, one character at a
+ time.
+
+`iso-2022-int-1'
+`iso-2022-int-1-dos'
+`iso-2022-int-1-mac'
+`iso-2022-int-1-unix'
+ Modeline indicator: `INT-1'. A type `iso2022' 7-bit coding system
+ with `ascii' (G0) and `korean-ksc5601' (G1) initially designated.
+ ISO-2022-INT-1.
+
+`iso-2022-jp-1978-irv'
+`iso-2022-jp-1978-irv-dos'
+`iso-2022-jp-1978-irv-mac'
+`iso-2022-jp-1978-irv-unix'
+ Modeline indicator: `Ja-78/7bit'. A type `iso2022' 7-bit coding
+ system. For compatibility with old Japanese terminals; if you
+ need to know, look at the source.
+
+`iso-2022-jp'
+`iso-2022-jp-2 (ISO7/SS)'
+`iso-2022-jp-dos'
+`iso-2022-jp-mac'
+`iso-2022-jp-unix'
+`iso-2022-jp-2-dos'
+`iso-2022-jp-2-mac'
+`iso-2022-jp-2-unix'
+ Modeline indicator: `MULE/7bit'. A type `iso2022' 7-bit coding
+ system with `ascii' (G0) initially designated, and complex
+ specifications to insure backward compatibility with old Japanese
+ systems. Used for communication with mail and news in Japan. The
+ "-2" versions also use SS2 to invoke a 96-charset one character at
+ a time.
+
+`iso-2022-kr'
+ Modeline indicator: `Ko/7bit' A type `iso2022' 7-bit coding
+ system with `ascii' (G0) and `korean-ksc5601' (G1) initially
+ designated. Used for e-mail in Korea.
+
+`iso-2022-lock'
+`iso-2022-lock-dos'
+`iso-2022-lock-mac'
+`iso-2022-lock-unix'
+ Modeline indicator: `ISO7/Lock'. A type `iso2022' 7-bit coding
+ system with `ascii' (G0) initially designated, using Locking-Shift
+ to invoke a 96-charset.
+
+`iso-8859-1'
+`iso-8859-1-dos'
+`iso-8859-1-mac'
+`iso-8859-1-unix'
+ Due to implementation, this is not a type `iso2022' coding system,
+ but rather an alias for the `raw-text' coding system.
+
+`iso-8859-2'
+`iso-8859-2-dos'
+`iso-8859-2-mac'
+`iso-8859-2-unix'
+ Modeline indicator: `MIME/Ltn-2'. A type `iso2022' coding system
+ with `ascii' (G0) and `latin-iso8859-2' (G1) initially invoked.
+
+`iso-8859-3'
+`iso-8859-3-dos'
+`iso-8859-3-mac'
+`iso-8859-3-unix'
+ Modeline indicator: `MIME/Ltn-3'. A type `iso2022' coding system
+ with `ascii' (G0) and `latin-iso8859-3' (G1) initially invoked.
+
+`iso-8859-4'
+`iso-8859-4-dos'
+`iso-8859-4-mac'
+`iso-8859-4-unix'
+ Modeline indicator: `MIME/Ltn-4'. A type `iso2022' coding system
+ with `ascii' (G0) and `latin-iso8859-4' (G1) initially invoked.
+
+`iso-8859-5'
+`iso-8859-5-dos'
+`iso-8859-5-mac'
+`iso-8859-5-unix'
+ Modeline indicator: `ISO8/Cyr'. A type `iso2022' coding system
+ with `ascii' (G0) and `cyrillic-iso8859-5' (G1) initially invoked.
+
+`iso-8859-7'
+`iso-8859-7-dos'
+`iso-8859-7-mac'
+`iso-8859-7-unix'
+ Modeline indicator: `Grk'. A type `iso2022' coding system with
+ `ascii' (G0) and `greek-iso8859-7' (G1) initially invoked.
+
+`iso-8859-8'
+`iso-8859-8-dos'
+`iso-8859-8-mac'
+`iso-8859-8-unix'
+ Modeline indicator: `MIME/Hbrw'. A type `iso2022' coding system
+ with `ascii' (G0) and `hebrew-iso8859-8' (G1) initially invoked.
+
+`iso-8859-9'
+`iso-8859-9-dos'
+`iso-8859-9-mac'
+`iso-8859-9-unix'
+ Modeline indicator: `MIME/Ltn-5'. A type `iso2022' coding system
+ with `ascii' (G0) and `latin-iso8859-9' (G1) initially invoked.
+
+`koi8-r'
+`koi8-r-dos'
+`koi8-r-mac'
+`koi8-r-unix'
+ Modeline indicator: `KOI8'. A type `ccl' coding-system used for
+ KOI8-R, an encoding of the Cyrillic alphabet.
+
+`shift_jis'
+`shift_jis-dos'
+`shift_jis-mac'
+`shift_jis-unix'
+ Modeline indicator: `Ja/SJIS'. A type `shift-jis' coding-system
+ implementing the Shift-JIS encoding for Japanese. The underscore
+ is to conform to the MIME charset implementing this encoding.
+
+`tis-620'
+`tis-620-dos'
+`tis-620-mac'
+`tis-620-unix'
+ Modeline indicator: `TIS620'. A type `ccl' encoding for Thai. The
+ external encoding is defined by TIS620, the internal encoding is
+ peculiar to MULE, and called `thai-xtis'.
+
+`viqr'
+ Modeline indicator: `VIQR'. A type `no-conversion' coding system
+ with Unix EOL convention (ie, no conversion) using
+ post-read-decode and pre-write-encode functions to translate the
+ VIQR coding system for Vietnamese.
+
+`viscii'
+`viscii-dos'
+`viscii-mac'
+`viscii-unix'
+ Modeline indicator: `VISCII'. A type `ccl' coding-system used for
+ VISCII 1.1 for Vietnamese. Differs slightly from VSCII; VISCII is
+ given priority by XEmacs.
+
+`vscii'
+`vscii-dos'
+`vscii-mac'
+`vscii-unix'
+ Modeline indicator: `VSCII'. A type `ccl' coding-system used for
+ VSCII 1.1 for Vietnamese. Differs slightly from VISCII, which is
+ given priority by XEmacs. Use `(prefer-coding-system
+ 'vietnamese-vscii)' to give priority to VSCII.
-`zmacs-update-region-hook'
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Index, Prev: Standard Hooks, Up: Top
+File: lispref.info, Node: CCL, Next: Category Tables, Prev: Coding Systems, Up: MULE
-Index
-*****
+CCL
+===
+
+ CCL (Code Conversion Language) is a simple structured programming
+language designed for character coding conversions. A CCL program is
+compiled to CCL code (represented by a vector of integers) and executed
+by the CCL interpreter embedded in Emacs. The CCL interpreter
+implements a virtual machine with 8 registers called `r0', ..., `r7', a
+number of control structures, and some I/O operators. Take care when
+using registers `r0' (used in implicit "set" statements) and especially
+`r7' (used internally by several statements and operations, especially
+for multiple return values and I/O operations).
+
+ CCL is used for code conversion during process I/O and file I/O for
+non-ISO2022 coding systems. (It is the only way for a user to specify a
+code conversion function.) It is also used for calculating the code
+point of an X11 font from a character code. However, since CCL is
+designed as a powerful programming language, it can be used for more
+generic calculation where efficiency is demanded. A combination of
+three or more arithmetic operations can be calculated faster by CCL than
+by Emacs Lisp.
+
+ *Warning:* The code in `src/mule-ccl.c' and
+`$packages/lisp/mule-base/mule-ccl.el' is the definitive description of
+CCL's semantics. The previous version of this section contained
+several typos and obsolete names left from earlier versions of MULE,
+and many may remain. (I am not an experienced CCL programmer; the few
+who know CCL well find writing English painful.)
+
+ A CCL program transforms an input data stream into an output data
+stream. The input stream, held in a buffer of constant bytes, is left
+unchanged. The buffer may be filled by an external input operation,
+taken from an Emacs buffer, or taken from a Lisp string. The output
+buffer is a dynamic array of bytes, which can be written by an external
+output operation, inserted into an Emacs buffer, or returned as a Lisp
+string.
+
+ A CCL program is a (Lisp) list containing two or three members. The
+first member is the "buffer magnification", which indicates the
+required minimum size of the output buffer as a multiple of the input
+buffer. It is followed by the "main block" which executes while there
+is input remaining, and an optional "EOF block" which is executed when
+the input is exhausted. Both the main block and the EOF block are CCL
+blocks.
+
+ A "CCL block" is either a CCL statement or list of CCL statements.
+A "CCL statement" is either a "set statement" (either an integer or an
+"assignment", which is a list of a register to receive the assignment,
+an assignment operator, and an expression) or a "control statement" (a
+list starting with a keyword, whose allowable syntax depends on the
+keyword).
+
+* Menu:
+
+* CCL Syntax:: CCL program syntax in BNF notation.
+* CCL Statements:: Semantics of CCL statements.
+* CCL Expressions:: Operators and expressions in CCL.
+* Calling CCL:: Running CCL programs.
+* CCL Examples:: The encoding functions for Big5 and KOI-8.
+
+\1f
+File: lispref.info, Node: CCL Syntax, Next: CCL Statements, Up: CCL
+
+CCL Syntax
+----------
+
+ The full syntax of a CCL program in BNF notation:
+
+CCL_PROGRAM :=
+ (BUFFER_MAGNIFICATION
+ CCL_MAIN_BLOCK
+ [ CCL_EOF_BLOCK ])
+
+BUFFER_MAGNIFICATION := integer
+CCL_MAIN_BLOCK := CCL_BLOCK
+CCL_EOF_BLOCK := CCL_BLOCK
+
+CCL_BLOCK :=
+ STATEMENT | (STATEMENT [STATEMENT ...])
+STATEMENT :=
+ SET | IF | BRANCH | LOOP | REPEAT | BREAK | READ | WRITE
+ | CALL | END
+
+SET :=
+ (REG = EXPRESSION)
+ | (REG ASSIGNMENT_OPERATOR EXPRESSION)
+ | integer
+
+EXPRESSION := ARG | (EXPRESSION OPERATOR ARG)
+
+IF := (if EXPRESSION CCL_BLOCK [CCL_BLOCK])
+BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
+LOOP := (loop STATEMENT [STATEMENT ...])
+BREAK := (break)
+REPEAT :=
+ (repeat)
+ | (write-repeat [REG | integer | string])
+ | (write-read-repeat REG [integer | ARRAY])
+READ :=
+ (read REG ...)
+ | (read-if (REG OPERATOR ARG) CCL_BLOCK CCL_BLOCK)
+ | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
+WRITE :=
+ (write REG ...)
+ | (write EXPRESSION)
+ | (write integer) | (write string) | (write REG ARRAY)
+ | string
+CALL := (call ccl-program-name)
+END := (end)
+
+REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
+ARG := REG | integer
+OPERATOR :=
+ + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
+ | < | > | == | <= | >= | != | de-sjis | en-sjis
+ASSIGNMENT_OPERATOR :=
+ += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
+ARRAY := '[' integer ... ']'
+
+\1f
+File: lispref.info, Node: CCL Statements, Next: CCL Expressions, Prev: CCL Syntax, Up: CCL
+
+CCL Statements
+--------------
+
+ The Emacs Code Conversion Language provides the following statement
+types: "set", "if", "branch", "loop", "repeat", "break", "read",
+"write", "call", and "end".
+
+Set statement:
+==============
+
+ The "set" statement has three variants with the syntaxes `(REG =
+EXPRESSION)', `(REG ASSIGNMENT_OPERATOR EXPRESSION)', and `INTEGER'.
+The assignment operator variation of the "set" statement works the same
+way as the corresponding C expression statement does. The assignment
+operators are `+=', `-=', `*=', `/=', `%=', `&=', `|=', `^=', `<<=',
+and `>>=', and they have the same meanings as in C. A "naked integer"
+INTEGER is equivalent to a SET statement of the form `(r0 = INTEGER)'.
+
+I/O statements:
+===============
+
+ The "read" statement takes one or more registers as arguments. It
+reads one byte (a C char) from the input into each register in turn.
+
+ The "write" takes several forms. In the form `(write REG ...)' it
+takes one or more registers as arguments and writes each in turn to the
+output. The integer in a register (interpreted as an Emchar) is
+encoded to multibyte form (ie, Bufbytes) and written to the current
+output buffer. If it is less than 256, it is written as is. The forms
+`(write EXPRESSION)' and `(write INTEGER)' are treated analogously.
+The form `(write STRING)' writes the constant string to the output. A
+"naked string" `STRING' is equivalent to the statement `(write
+STRING)'. The form `(write REG ARRAY)' writes the REGth element of the
+ARRAY to the output.
+
+Conditional statements:
+=======================
+
+ The "if" statement takes an EXPRESSION, a CCL BLOCK, and an optional
+SECOND CCL BLOCK as arguments. If the EXPRESSION evaluates to
+non-zero, the first CCL BLOCK is executed. Otherwise, if there is a
+SECOND CCL BLOCK, it is executed.
+
+ The "read-if" variant of the "if" statement takes an EXPRESSION, a
+CCL BLOCK, and an optional SECOND CCL BLOCK as arguments. The
+EXPRESSION must have the form `(REG OPERATOR OPERAND)' (where OPERAND is
+a register or an integer). The `read-if' statement first reads from
+the input into the first register operand in the EXPRESSION, then
+conditionally executes a CCL block just as the `if' statement does.
+
+ The "branch" statement takes an EXPRESSION and one or more CCL
+blocks as arguments. The CCL blocks are treated as a zero-indexed
+array, and the `branch' statement uses the EXPRESSION as the index of
+the CCL block to execute. Null CCL blocks may be used as no-ops,
+continuing execution with the statement following the `branch'
+statement in the containing CCL block. Out-of-range values for the
+EXPRESSION are also treated as no-ops.
+
+ The "read-branch" variant of the "branch" statement takes an
+REGISTER, a CCL BLOCK, and an optional SECOND CCL BLOCK as arguments.
+The `read-branch' statement first reads from the input into the
+REGISTER, then conditionally executes a CCL block just as the `branch'
+statement does.
+
+Loop control statements:
+========================
+
+ The "loop" statement creates a block with an implied jump from the
+end of the block back to its head. The loop is exited on a `break'
+statement, and continued without executing the tail by a `repeat'
+statement.
+
+ The "break" statement, written `(break)', terminates the current
+loop and continues with the next statement in the current block.
+
+ The "repeat" statement has three variants, `repeat', `write-repeat',
+and `write-read-repeat'. Each continues the current loop from its
+head, possibly after performing I/O. `repeat' takes no arguments and
+does no I/O before jumping. `write-repeat' takes a single argument (a
+register, an integer, or a string), writes it to the output, then jumps.
+`write-read-repeat' takes one or two arguments. The first must be a
+register. The second may be an integer or an array; if absent, it is
+implicitly set to the first (register) argument. `write-read-repeat'
+writes its second argument to the output, then reads from the input
+into the register, and finally jumps. See the `write' and `read'
+statements for the semantics of the I/O operations for each type of
+argument.
+
+Other control statements:
+=========================
+
+ The "call" statement, written `(call CCL-PROGRAM-NAME)', executes a
+CCL program as a subroutine. It does not return a value to the caller,
+but can modify the register status.
+
+ The "end" statement, written `(end)', terminates the CCL program
+successfully, and returns to caller (which may be a CCL program). It
+does not alter the status of the registers.
+
+\1f
+File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL
+
+CCL Expressions
+---------------
+
+ CCL, unlike Lisp, uses infix expressions. The simplest CCL
+expressions consist of a single OPERAND, either a register (one of `r0',
+..., `r0') or an integer. Complex expressions are lists of the form `(
+EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not
+expressions.
+
+ In the following table, X is the target resister for a "set". In
+subexpressions, this is implicitly `r7'. This means that `>8', `//',
+`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since
+they return parts of their values in `r7'. Y may be an expression,
+register, or integer, while Z must be a register or an integer.
+
+Name Operator Code C-like Description
+CCL_PLUS `+' 0x00 X = Y + Z
+CCL_MINUS `-' 0x01 X = Y - Z
+CCL_MUL `*' 0x02 X = Y * Z
+CCL_DIV `/' 0x03 X = Y / Z
+CCL_MOD `%' 0x04 X = Y % Z
+CCL_AND `&' 0x05 X = Y & Z
+CCL_OR `|' 0x06 X = Y | Z
+CCL_XOR `^' 0x07 X = Y ^ Z
+CCL_LSH `<<' 0x08 X = Y << Z
+CCL_RSH `>>' 0x09 X = Y >> Z
+CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z
+CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF
+CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z
+CCL_LS `<' 0x10 X = (X < Y)
+CCL_GT `>' 0x11 X = (X > Y)
+CCL_EQ `==' 0x12 X = (X == Y)
+CCL_LE `<=' 0x13 X = (X <= Y)
+CCL_GE `>=' 0x14 X = (X >= Y)
+CCL_NE `!=' 0x15 X = (X != Y)
+CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z))
+ r[7] = LOWER_BYTE (SJIS (Y, Z)
+CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z))
+ r[7] = LOWER_BYTE (DE-SJIS (Y, Z))
+
+ The CCL operators are as in C, with the addition of CCL_LSH8,
+CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The
+CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes
+as the high and low bytes of a two-byte character code. (SJIS stands
+for Shift JIS, an encoding of Japanese characters used by Microsoft.
+CCL_ENCODE_SJIS is a complicated transformation of the Japanese
+standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.)
+It is somewhat odd to represent the SJIS operations in infix form.
+
+\1f
+File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL
+
+Calling CCL
+-----------
+
+ CCL programs are called automatically during Emacs buffer I/O when
+the external representation has a coding system type of `shift-jis',
+`big5', or `ccl'. The program is specified by the coding system (*note
+Coding Systems::). You can also call CCL programs from other CCL
+programs, and from Lisp using these functions:
+
+ - Function: ccl-execute ccl-program status
+ Execute CCL-PROGRAM with registers initialized by STATUS.
+ CCL-PROGRAM is a vector of compiled CCL code created by
+ `ccl-compile'. It is an error for the program to try to execute a
+ CCL I/O command. STATUS must be a vector of nine values,
+ specifying the initial value for the R0, R1 .. R7 registers and
+ for the instruction counter IC. A `nil' value for a register
+ initializer causes the register to be set to 0. A `nil' value for
+ the IC initializer causes execution to start at the beginning of
+ the program. When the program is done, STATUS is modified (by
+ side-effect) to contain the ending values for the corresponding
+ registers and IC.
+
+ - Function: ccl-execute-on-string ccl-program status str &optional
+ continue
+ Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is
+ a vector of compiled CCL code created by `ccl-compile'. STATUS
+ must be a vector of nine values, specifying the initial value for
+ the R0, R1 .. R7 registers and for the instruction counter IC. A
+ `nil' value for a register initializer causes the register to be
+ set to 0. A `nil' value for the IC initializer causes execution
+ to start at the beginning of the program. An optional fourth
+ argument CONTINUE, if non-nil, causes the IC to remain on the
+ unsatisfied read operation if the program terminates due to
+ exhaustion of the input buffer. Otherwise the IC is set to the end
+ of the program. When the program is done, STATUS is modified (by
+ side-effect) to contain the ending values for the corresponding
+ registers and IC. Returns the resulting string.
+
+ To call a CCL program from another CCL program, it must first be
+registered:
+
+ - Function: register-ccl-program name ccl-program
+ Register NAME for CCL program PROGRAM in `ccl-program-table'.
+ PROGRAM should be the compiled form of a CCL program, or nil.
+ Return index number of the registered CCL program.
+
+ Information about the processor time used by the CCL interpreter can
+be obtained using these functions:
+
+ - Function: ccl-elapsed-time
+ Returns the elapsed processor time of the CCL interpreter as cons
+ of user and system time, as floating point numbers measured in
+ seconds. If only one overall value can be determined, the return
+ value will be a cons of that value and 0.
+
+ - Function: ccl-reset-elapsed-time
+ Resets the CCL interpreter's internal elapsed time registers.
+
+\1f
+File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL
+
+CCL Examples
+------------
+
+ This section is not yet written.
+
+\1f
+File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE
+
+Category Tables
+===============
+
+ A category table is a type of char table used for keeping track of
+categories. Categories are used for classifying characters for use in
+regexps--you can refer to a category rather than having to use a
+complicated [] expression (and category lookups are significantly
+faster).
+
+ There are 95 different categories available, one for each printable
+character (including space) in the ASCII charset. Each category is
+designated by one such character, called a "category designator". They
+are specified in a regexp using the syntax `\cX', where X is a category
+designator. (This is not yet implemented.)
+
+ A category table specifies, for each character, the categories that
+the character is in. Note that a character can be in more than one
+category. More specifically, a category table maps from a character to
+either the value `nil' (meaning the character is in no categories) or a
+95-element bit vector, specifying for each of the 95 categories whether
+the character is in that category.
+
+ Special Lisp functions are provided that abstract this, so you do not
+have to directly manipulate bit vectors.
+
+ - Function: category-table-p obj
+ This function returns `t' if ARG is a category table.
+
+ - Function: category-table &optional buffer
+ This function returns the current category table. This is the one
+ specified by the current buffer, or by BUFFER if it is non-`nil'.
+
+ - Function: standard-category-table
+ This function returns the standard category table. This is the
+ one used for new buffers.
+
+ - Function: copy-category-table &optional table
+ This function constructs a new category table and return it. It
+ is a copy of the TABLE, which defaults to the standard category
+ table.
+
+ - Function: set-category-table table &optional buffer
+ This function selects a new category table for BUFFER. One
+ argument, a category table. BUFFER defaults to the current buffer
+ if omitted.
+
+ - Function: category-designator-p obj
+ This function returns `t' if ARG is a category designator (a char
+ in the range `' '' to `'~'').
+
+ - Function: category-table-value-p obj
+ This function returns `t' if ARG is a category table value. Valid
+ values are `nil' or a bit vector of size 95.
+
+\1f
+File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top
+
+Tips and Standards
+******************
+
+ This chapter describes no additional features of XEmacs Lisp.
+Instead it gives advice on making effective use of the features
+described in the previous chapters.
+
+* Menu:
+
+* Style Tips:: Writing clean and robust programs.
+* Compilation Tips:: Making compiled code run fast.
+* Documentation Tips:: Writing readable documentation strings.
+* Comment Tips:: Conventions for writing comments.
+* Library Headers:: Standard headers for library packages.
+
+\1f
+File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips
+
+Writing Clean Lisp Programs
+===========================
+
+ Here are some tips for avoiding common errors in writing Lisp code
+intended for widespread use:
+
+ * Since all global variables share the same name space, and all
+ functions share another name space, you should choose a short word
+ to distinguish your program from other Lisp programs. Then take
+ care to begin the names of all global variables, constants, and
+ functions with the chosen prefix. This helps avoid name conflicts.
+
+ This recommendation applies even to names for traditional Lisp
+ primitives that are not primitives in XEmacs Lisp--even to `cadr'.
+ Believe it or not, there is more than one plausible way to define
+ `cadr'. Play it safe; append your name prefix to produce a name
+ like `foo-cadr' or `mylib-cadr' instead.
+
+ If you write a function that you think ought to be added to Emacs
+ under a certain name, such as `twiddle-files', don't call it by
+ that name in your program. Call it `mylib-twiddle-files' in your
+ program, and send mail to `bug-gnu-emacs@prep.ai.mit.edu'
+ suggesting we add it to Emacs. If and when we do, we can change
+ the name easily enough.
+
+ If one prefix is insufficient, your package may use two or three
+ alternative common prefixes, so long as they make sense.
+
+ Separate the prefix from the rest of the symbol name with a hyphen,
+ `-'. This will be consistent with XEmacs itself and with most
+ Emacs Lisp programs.
+
+ * It is often useful to put a call to `provide' in each separate
+ library program, at least if there is more than one entry point to
+ the program.
+
+ * If a file requires certain other library programs to be loaded
+ beforehand, then the comments at the beginning of the file should
+ say so. Also, use `require' to make sure they are loaded.
+
+ * If one file FOO uses a macro defined in another file BAR, FOO
+ should contain this expression before the first use of the macro:
+
+ (eval-when-compile (require 'BAR))
+
+ (And BAR should contain `(provide 'BAR)', to make the `require'
+ work.) This will cause BAR to be loaded when you byte-compile
+ FOO. Otherwise, you risk compiling FOO without the necessary
+ macro loaded, and that would produce compiled code that won't work
+ right. *Note Compiling Macros::.
+
+ Using `eval-when-compile' avoids loading BAR when the compiled
+ version of FOO is _used_.
+
+ * If you define a major mode, make sure to run a hook variable using
+ `run-hooks', just as the existing major modes do. *Note Hooks::.
+
+ * If the purpose of a function is to tell you whether a certain
+ condition is true or false, give the function a name that ends in
+ `p'. If the name is one word, add just `p'; if the name is
+ multiple words, add `-p'. Examples are `framep' and
+ `frame-live-p'.
+
+ * If a user option variable records a true-or-false condition, give
+ it a name that ends in `-flag'.
+
+ * Please do not define `C-c LETTER' as a key in your major modes.
+ These sequences are reserved for users; they are the *only*
+ sequences reserved for users, so we cannot do without them.
+
+ Instead, define sequences consisting of `C-c' followed by a
+ non-letter. These sequences are reserved for major modes.
+
+ Changing all the major modes in Emacs 18 so they would follow this
+ convention was a lot of work. Abandoning this convention would
+ make that work go to waste, and inconvenience users.
+
+ * Sequences consisting of `C-c' followed by `{', `}', `<', `>', `:'
+ or `;' are also reserved for major modes.
+
+ * Sequences consisting of `C-c' followed by any other punctuation
+ character are allocated for minor modes. Using them in a major
+ mode is not absolutely prohibited, but if you do that, the major
+ mode binding may be shadowed from time to time by minor modes.
+
+ * You should not bind `C-h' following any prefix character (including
+ `C-c'). If you don't bind `C-h', it is automatically available as
+ a help character for listing the subcommands of the prefix
+ character.
+
+ * You should not bind a key sequence ending in <ESC> except following
+ another <ESC>. (That is, it is ok to bind a sequence ending in
+ `<ESC> <ESC>'.)
+
+ The reason for this rule is that a non-prefix binding for <ESC> in
+ any context prevents recognition of escape sequences as function
+ keys in that context.
+
+ * Applications should not bind mouse events based on button 1 with
+ the shift key held down. These events include `S-mouse-1',
+ `M-S-mouse-1', `C-S-mouse-1', and so on. They are reserved for
+ users.
+
+ * Modes should redefine `mouse-2' as a command to follow some sort of
+ reference in the text of a buffer, if users usually would not want
+ to alter the text in that buffer by hand. Modes such as Dired,
+ Info, Compilation, and Occur redefine it in this way.
+
+ * When a package provides a modification of ordinary Emacs behavior,
+ it is good to include a command to enable and disable the feature,
+ Provide a command named `WHATEVER-mode' which turns the feature on
+ or off, and make it autoload (*note Autoload::). Design the
+ package so that simply loading it has no visible effect--that
+ should not enable the feature. Users will request the feature by
+ invoking the command.
+
+ * It is a bad idea to define aliases for the Emacs primitives. Use
+ the standard names instead.
+
+ * Redefining an Emacs primitive is an even worse idea. It may do
+ the right thing for a particular program, but there is no telling
+ what other programs might break as a result.
+
+ * If a file does replace any of the functions or library programs of
+ standard XEmacs, prominent comments at the beginning of the file
+ should say which functions are replaced, and how the behavior of
+ the replacements differs from that of the originals.
+
+ * Please keep the names of your XEmacs Lisp source files to 13
+ characters or less. This way, if the files are compiled, the
+ compiled files' names will be 14 characters or less, which is
+ short enough to fit on all kinds of Unix systems.
+
+ * Don't use `next-line' or `previous-line' in programs; nearly
+ always, `forward-line' is more convenient as well as more
+ predictable and robust. *Note Text Lines::.
+
+ * Don't call functions that set the mark, unless setting the mark is
+ one of the intended features of your program. The mark is a
+ user-level feature, so it is incorrect to change the mark except
+ to supply a value for the user's benefit. *Note The Mark::.
+
+ In particular, don't use these functions:
+
+ * `beginning-of-buffer', `end-of-buffer'
+
+ * `replace-string', `replace-regexp'
+
+ If you just want to move point, or replace a certain string,
+ without any of the other features intended for interactive users,
+ you can replace these functions with one or two lines of simple
+ Lisp code.
+
+ * Use lists rather than vectors, except when there is a particular
+ reason to use a vector. Lisp has more facilities for manipulating
+ lists than for vectors, and working with lists is usually more
+ convenient.
+
+ Vectors are advantageous for tables that are substantial in size
+ and are accessed in random order (not searched front to back),
+ provided there is no need to insert or delete elements (only lists
+ allow that).
+
+ * The recommended way to print a message in the echo area is with
+ the `message' function, not `princ'. *Note The Echo Area::.
+
+ * When you encounter an error condition, call the function `error'
+ (or `signal'). The function `error' does not return. *Note
+ Signaling Errors::.
+
+ Do not use `message', `throw', `sleep-for', or `beep' to report
+ errors.
+
+ * An error message should start with a capital letter but should not
+ end with a period.
+
+ * Try to avoid using recursive edits. Instead, do what the Rmail `e'
+ command does: use a new local keymap that contains one command
+ defined to switch back to the old local keymap. Or do what the
+ `edit-options' command does: switch to another buffer and let the
+ user switch back at will. *Note Recursive Editing::.
+
+ * In some other systems there is a convention of choosing variable
+ names that begin and end with `*'. We don't use that convention
+ in Emacs Lisp, so please don't use it in your programs. (Emacs
+ uses such names only for program-generated buffers.) The users
+ will find Emacs more coherent if all libraries use the same
+ conventions.
+
+ * Indent each function with `C-M-q' (`indent-sexp') using the
+ default indentation parameters.
+
+ * Don't make a habit of putting close-parentheses on lines by
+ themselves; Lisp programmers find this disconcerting. Once in a
+ while, when there is a sequence of many consecutive
+ close-parentheses, it may make sense to split them in one or two
+ significant places.
+
+ * Please put a copyright notice on the file if you give copies to
+ anyone. Use the same lines that appear at the top of the Lisp
+ files in XEmacs itself. If you have not signed papers to assign
+ the copyright to the Foundation, then place your name in the
+ copyright notice in place of the Foundation's name.
+
+\1f
+File: lispref.info, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips
+
+Tips for Making Compiled Code Fast
+==================================
+
+ Here are ways of improving the execution speed of byte-compiled Lisp
+programs.
+
+ * Use the `profile' library to profile your program. See the file
+ `profile.el' for instructions.
+
+ * Use iteration rather than recursion whenever possible. Function
+ calls are slow in XEmacs Lisp even when a compiled function is
+ calling another compiled function.
+
+ * Using the primitive list-searching functions `memq', `member',
+ `assq', or `assoc' is even faster than explicit iteration. It may
+ be worth rearranging a data structure so that one of these
+ primitive search functions can be used.
+
+ * Certain built-in functions are handled specially in byte-compiled
+ code, avoiding the need for an ordinary function call. It is a
+ good idea to use these functions rather than alternatives. To see
+ whether a function is handled specially by the compiler, examine
+ its `byte-compile' property. If the property is non-`nil', then
+ the function is handled specially.
+
+ For example, the following input will show you that `aref' is
+ compiled specially (*note Array Functions::) while `elt' is not
+ (*note Sequence Functions::):
+
+ (get 'aref 'byte-compile)
+ => byte-compile-two-args
+
+ (get 'elt 'byte-compile)
+ => nil
+
+ * If calling a small function accounts for a substantial part of
+ your program's running time, make the function inline. This
+ eliminates the function call overhead. Since making a function
+ inline reduces the flexibility of changing the program, don't do
+ it unless it gives a noticeable speedup in something slow enough
+ that users care about the speed. *Note Inline Functions::.
+
+\1f
+File: lispref.info, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips
+
+Tips for Documentation Strings
+==============================
+
+ Here are some tips for the writing of documentation strings.
+
+ * Every command, function, or variable intended for users to know
+ about should have a documentation string.
+
+ * An internal variable or subroutine of a Lisp program might as well
+ have a documentation string. In earlier Emacs versions, you could
+ save space by using a comment instead of a documentation string,
+ but that is no longer the case.
+
+ * The first line of the documentation string should consist of one
+ or two complete sentences that stand on their own as a summary.
+ `M-x apropos' displays just the first line, and if it doesn't
+ stand on its own, the result looks bad. In particular, start the
+ first line with a capital letter and end with a period.
+
+ The documentation string can have additional lines that expand on
+ the details of how to use the function or variable. The
+ additional lines should be made up of complete sentences also, but
+ they may be filled if that looks good.
+
+ * For consistency, phrase the verb in the first sentence of a
+ documentation string as an infinitive with "to" omitted. For
+ instance, use "Return the cons of A and B." in preference to
+ "Returns the cons of A and B." Usually it looks good to do
+ likewise for the rest of the first paragraph. Subsequent
+ paragraphs usually look better if they have proper subjects.
+
+ * Write documentation strings in the active voice, not the passive,
+ and in the present tense, not the future. For instance, use
+ "Return a list containing A and B." instead of "A list containing
+ A and B will be returned."
+
+ * Avoid using the word "cause" (or its equivalents) unnecessarily.
+ Instead of, "Cause Emacs to display text in boldface," write just
+ "Display text in boldface."
+
+ * Do not start or end a documentation string with whitespace.
+
+ * Format the documentation string so that it fits in an Emacs window
+ on an 80-column screen. It is a good idea for most lines to be no
+ wider than 60 characters. The first line can be wider if
+ necessary to fit the information that ought to be there.
+
+ However, rather than simply filling the entire documentation
+ string, you can make it much more readable by choosing line breaks
+ with care. Use blank lines between topics if the documentation
+ string is long.
+
+ * *Do not* indent subsequent lines of a documentation string so that
+ the text is lined up in the source code with the text of the first
+ line. This looks nice in the source code, but looks bizarre when
+ users view the documentation. Remember that the indentation
+ before the starting double-quote is not part of the string!
+
+ * A variable's documentation string should start with `*' if the
+ variable is one that users would often want to set interactively.
+ If the value is a long list, or a function, or if the variable
+ would be set only in init files, then don't start the
+ documentation string with `*'. *Note Defining Variables::.
+
+ * The documentation string for a variable that is a yes-or-no flag
+ should start with words such as "Non-nil means...", to make it
+ clear that all non-`nil' values are equivalent and indicate
+ explicitly what `nil' and non-`nil' mean.
+
+ * When a function's documentation string mentions the value of an
+ argument of the function, use the argument name in capital letters
+ as if it were a name for that value. Thus, the documentation
+ string of the function `/' refers to its second argument as
+ `DIVISOR', because the actual argument name is `divisor'.
+
+ Also use all caps for meta-syntactic variables, such as when you
+ show the decomposition of a list or vector into subunits, some of
+ which may vary.
+
+ * When a documentation string refers to a Lisp symbol, write it as it
+ would be printed (which usually means in lower case), with
+ single-quotes around it. For example: `lambda'. There are two
+ exceptions: write t and nil without single-quotes. (In this
+ manual, we normally do use single-quotes for those symbols.)
+
+ * Don't write key sequences directly in documentation strings.
+ Instead, use the `\\[...]' construct to stand for them. For
+ example, instead of writing `C-f', write `\\[forward-char]'. When
+ Emacs displays the documentation string, it substitutes whatever
+ key is currently bound to `forward-char'. (This is normally `C-f',
+ but it may be some other character if the user has moved key
+ bindings.) *Note Keys in Documentation::.
+
+ * In documentation strings for a major mode, you will want to refer
+ to the key bindings of that mode's local map, rather than global
+ ones. Therefore, use the construct `\\<...>' once in the
+ documentation string to specify which key map to use. Do this
+ before the first use of `\\[...]'. The text inside the `\\<...>'
+ should be the name of the variable containing the local keymap for
+ the major mode.
+
+ It is not practical to use `\\[...]' very many times, because
+ display of the documentation string will become slow. So use this
+ to describe the most important commands in your major mode, and
+ then use `\\{...}' to display the rest of the mode's keymap.
+
+\1f
+File: lispref.info, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips
+
+Tips on Writing Comments
+========================
+
+ We recommend these conventions for where to put comments and how to
+indent them:
+
+`;'
+ Comments that start with a single semicolon, `;', should all be
+ aligned to the same column on the right of the source code. Such
+ comments usually explain how the code on the same line does its
+ job. In Lisp mode and related modes, the `M-;'
+ (`indent-for-comment') command automatically inserts such a `;' in
+ the right place, or aligns such a comment if it is already present.
+
+ This and following examples are taken from the Emacs sources.
+
+ (setq base-version-list ; there was a base
+ (assoc (substring fn 0 start-vn) ; version to which
+ file-version-assoc-list)) ; this looks like
+ ; a subversion
+
+`;;'
+ Comments that start with two semicolons, `;;', should be aligned to
+ the same level of indentation as the code. Such comments usually
+ describe the purpose of the following lines or the state of the
+ program at that point. For example:
+
+ (prog1 (setq auto-fill-function
+ ...
+ ...
+ ;; update modeline
+ (redraw-modeline)))
+
+ Every function that has no documentation string (because it is use
+ only internally within the package it belongs to), should have
+ instead a two-semicolon comment right before the function,
+ explaining what the function does and how to call it properly.
+ Explain precisely what each argument means and how the function
+ interprets its possible values.
+
+`;;;'
+ Comments that start with three semicolons, `;;;', should start at
+ the left margin. Such comments are used outside function
+ definitions to make general statements explaining the design
+ principles of the program. For example:
+
+ ;;; This Lisp code is run in XEmacs
+ ;;; when it is to operate as a server
+ ;;; for other processes.
+
+ Another use for triple-semicolon comments is for commenting out
+ lines within a function. We use triple-semicolons for this
+ precisely so that they remain at the left margin.
+
+ (defun foo (a)
+ ;;; This is no longer necessary.
+ ;;; (force-mode-line-update)
+ (message "Finished with %s" a))
+
+`;;;;'
+ Comments that start with four semicolons, `;;;;', should be aligned
+ to the left margin and are used for headings of major sections of a
+ program. For example:
+
+ ;;;; The kill ring
+
+The indentation commands of the Lisp modes in XEmacs, such as `M-;'
+(`indent-for-comment') and <TAB> (`lisp-indent-line') automatically
+indent comments according to these conventions, depending on the number
+of semicolons. *Note Manipulating Comments: (emacs)Comments.
+
+\1f
+File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips
+
+Conventional Headers for XEmacs Libraries
+=========================================
+
+ XEmacs has conventions for using special comments in Lisp libraries
+to divide them into sections and give information such as who wrote
+them. This section explains these conventions. First, an example:
+
+ ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
+
+ ;; Copyright (C) 1992 Free Software Foundation, Inc.
+
+ ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
+ ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
+ ;; Created: 14 Jul 1992
+ ;; Version: 1.2
+ ;; Keywords: docs
+
+ ;; This file is part of XEmacs.
+ COPYING PERMISSIONS...
+
+ The very first line should have this format:
+
+ ;;; FILENAME --- DESCRIPTION
+
+The description should be complete in one line.
+
+ After the copyright notice come several "header comment" lines, each
+beginning with `;; HEADER-NAME:'. Here is a table of the conventional
+possibilities for HEADER-NAME:
+
+`Author'
+ This line states the name and net address of at least the principal
+ author of the library.
+
+ If there are multiple authors, you can list them on continuation
+ lines led by `;;' and a tab character, like this:
+
+ ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
+ ;; Dave Sill <de5@ornl.gov>
+ ;; Dave Brennan <brennan@hal.com>
+ ;; Eric Raymond <esr@snark.thyrsus.com>
+
+`Maintainer'
+ This line should contain a single name/address as in the Author
+ line, or an address only, or the string `FSF'. If there is no
+ maintainer line, the person(s) in the Author field are presumed to
+ be the maintainers. The example above is mildly bogus because the
+ maintainer line is redundant.
+
+ The idea behind the `Author' and `Maintainer' lines is to make
+ possible a Lisp function to "send mail to the maintainer" without
+ having to mine the name out by hand.
+
+ Be sure to surround the network address with `<...>' if you
+ include the person's full name as well as the network address.
+
+`Created'
+ This optional line gives the original creation date of the file.
+ For historical interest only.
+
+`Version'
+ If you wish to record version numbers for the individual Lisp
+ program, put them in this line.
+
+`Adapted-By'
+ In this header line, place the name of the person who adapted the
+ library for installation (to make it fit the style conventions, for
+ example).
+
+`Keywords'
+ This line lists keywords for the `finder-by-keyword' help command.
+ This field is important; it's how people will find your package
+ when they're looking for things by topic area. To separate the
+ keywords, you can use spaces, commas, or both.
+
+ Just about every Lisp library ought to have the `Author' and
+`Keywords' header comment lines. Use the others if they are
+appropriate. You can also put in header lines with other header
+names--they have no standard meanings, so they can't do any harm.
+
+ We use additional stylized comments to subdivide the contents of the
+library file. Here is a table of them:
+
+`;;; Commentary:'
+ This begins introductory comments that explain how the library
+ works. It should come right after the copying permissions.
+
+`;;; Change log:'
+ This begins change log information stored in the library file (if
+ you store the change history there). For most of the Lisp files
+ distributed with XEmacs, the change history is kept in the file
+ `ChangeLog' and not in the source file at all; these files do not
+ have a `;;; Change log:' line.
+
+`;;; Code:'
+ This begins the actual code of the program.
+
+`;;; FILENAME ends here'
+ This is the "footer line"; it appears at the very end of the file.
+ Its purpose is to enable people to detect truncated versions of
+ the file from the lack of a footer line.
+
+\1f
+File: lispref.info, Node: Building XEmacs and Object Allocation, Next: Standard Errors, Prev: Tips, Up: Top
+
+Building XEmacs; Allocation of Objects
+**************************************
+
+ This chapter describes how the runnable XEmacs executable is dumped
+with the preloaded Lisp libraries in it and how storage is allocated.
+
+ There is an entire separate document, the `XEmacs Internals Manual',
+devoted to the internals of XEmacs from the perspective of the C
+programmer. It contains much more detailed information about the build
+process, the allocation and garbage-collection process, and other
+aspects related to the internals of XEmacs.
* Menu:
-* " in printing: Output Functions.
-* " in strings: String Type.
-* #$: Docs and Compilation.
-* #@COUNT: Docs and Compilation.
-* $ in display: Truncation.
-* $ in regexp: Syntax of Regexps.
-* %: Arithmetic Operations.
-* % in format: Formatting Strings.
-* & in replacement: Replacing Match.
-* &define (Edebug): Specification List.
-* ¬ (Edebug): Specification List.
-* &optional: Argument List.
-* &optional (Edebug): Specification List.
-* &or (Edebug): Specification List.
-* &rest: Argument List.
-* &rest (Edebug): Specification List.
-* ' for quoting: Quoting.
-* ( in regexp: Syntax of Regexps.
-* (...) in lists: Cons Cell Type.
-* ) in regexp: Syntax of Regexps.
-* *: Arithmetic Operations.
-* * in interactive: Using Interactive.
-* * in regexp: Syntax of Regexps.
-* *? in regexp: Syntax of Regexps.
-* *scratch*: Auto Major Mode.
-* +: Arithmetic Operations.
-* + in regexp: Syntax of Regexps.
-* +? in regexp: Syntax of Regexps.
-* , (with Backquote): Backquote.
-* ,@ (with Backquote): Backquote.
-* -: Arithmetic Operations.
-* . in lists: Dotted Pair Notation.
-* . in regexp: Syntax of Regexps.
-* .emacs: Init File.
-* .emacs customization: Major Mode Conventions.
-* /: Arithmetic Operations.
-* /=: Comparison of Numbers.
-* 1+: Arithmetic Operations.
-* 1-: Arithmetic Operations.
-* ; in comment: Comments.
-* <: Comparison of Numbers.
-* <=: Comparison of Numbers.
-* <ESC>: Functions for Key Lookup.
-* =: Comparison of Numbers.
-* >: Comparison of Numbers.
-* >=: Comparison of Numbers.
-* ? in character constant: Character Type.
-* ? in regexp: Syntax of Regexps.
-* @ in interactive: Using Interactive.
-* [ in regexp: Syntax of Regexps.
-* [...] (Edebug): Specification List.
-* \ in character constant: Character Type.
-* \ in display: Truncation.
-* \ in printing: Output Functions.
-* \ in regexp: Syntax of Regexps.
-* \ in replacement: Replacing Match.
-* \ in strings: String Type.
-* \ in symbols: Symbol Type.
-* \' in regexp: Syntax of Regexps.
-* \(?: in regexp: Syntax of Regexps.
-* \< in regexp: Syntax of Regexps.
-* \= in regexp: Syntax of Regexps.
-* \> in regexp: Syntax of Regexps.
-* \` in regexp: Syntax of Regexps.
-* \a: Character Type.
-* \b: Character Type.
-* \B in regexp: Syntax of Regexps.
-* \b in regexp: Syntax of Regexps.
-* \e: Character Type.
-* \f: Character Type.
-* \n: Character Type.
-* \n in print: Output Variables.
-* \N in replacement: Replacing Match.
-* \r: Character Type.
-* \S in regexp: Syntax of Regexps.
-* \s in regexp: Syntax of Regexps.
-* \t: Character Type.
-* \v: Character Type.
-* \W in regexp: Syntax of Regexps.
-* \w in regexp: Syntax of Regexps.
-* \{n,m\} in regexp: Syntax of Regexps.
-* ] in regexp: Syntax of Regexps.
-* ^ in regexp: Syntax of Regexps.
-* _ in interactive: Using Interactive.
-* `: Backquote.
-* ` (Edebug): Debugging Backquote.
-* ` (list substitution): Backquote.
-* abbrev: Abbrevs.
-* abbrev table: Abbrevs.
-* abbrev tables in modes: Major Mode Conventions.
-* abbrev-all-caps: Abbrev Expansion.
-* abbrev-expansion: Abbrev Expansion.
-* abbrev-file-name: Abbrev Files.
-* abbrev-mode: Abbrev Mode.
-* abbrev-prefix-mark: Abbrev Expansion.
-* abbrev-start-location: Abbrev Expansion.
-* abbrev-start-location-buffer: Abbrev Expansion.
-* abbrev-symbol: Abbrev Expansion.
-* abbrev-table-name-list: Abbrev Tables.
-* abbreviate-file-name: Directory Names.
-* abbrevs-changed: Abbrev Files.
-* abort-recursive-edit: Recursive Editing.
-* aborting: Recursive Editing.
-* abs: Arithmetic Operations.
-* absolute file name: Relative File Names.
-* accelerate-menu: Menu Accelerator Functions.
-* accept-process-output: Accepting Output.
-* accessibility of a file: Testing Accessibility.
-* accessible portion (of a buffer): Narrowing.
-* accessible-keymaps: Scanning Keymaps.
-* acos: Math Functions.
-* acosh: Math Functions.
-* activate-menubar-hook: Menubar.
-* activate-popup-menu-hook: Pop-Up Menus.
-* active display table: Active Display Table.
-* active keymap: Active Keymaps.
-* active-minibuffer-window: Minibuffer Misc.
-* add-abbrev: Defining Abbrevs.
-* add-hook: Hooks.
-* add-menu: Modifying Menus.
-* add-menu-button: Modifying Menus.
-* add-menu-item: Modifying Menus.
-* add-name-to-file: Changing File Attributes.
-* add-spec-list-to-specifier: Adding Specifications.
-* add-spec-to-specifier: Adding Specifications.
-* add-submenu: Modifying Menus.
-* add-text-properties: Changing Properties.
-* add-timeout: Timers.
-* add-to-list: Setting Variables.
-* add-tooltalk-message-arg: Elisp Interface for Sending Messages.
-* add-tooltalk-pattern-arg: Elisp Interface for Receiving Messages.
-* add-tooltalk-pattern-attribute: Elisp Interface for Receiving Messages.
-* address field of register: Cons Cell Type.
-* after-change-function: Change Hooks.
-* after-change-functions: Change Hooks.
-* after-find-file: Subroutines of Visiting.
-* after-init-hook: Init File.
-* after-insert-file-functions: Saving Properties.
-* after-load-alist: Hooks for Loading.
-* after-revert-hook: Reverting.
-* after-save-hook: Saving Buffers.
-* aliases, for variables: Variable Aliases.
-* alist: Association Lists.
-* alist-to-plist: Converting Plists To/From Alists.
-* all-annotations: Locating Annotations.
-* all-completions: Basic Completion.
-* and: Combining Conditions.
-* annotation: Annotations.
-* annotation hooks: Annotation Hooks.
-* annotation-action: Annotation Properties.
-* annotation-data: Annotation Properties.
-* annotation-down-glyph: Annotation Properties.
-* annotation-face: Annotation Properties.
-* annotation-glyph: Annotation Properties.
-* annotation-layout: Annotation Properties.
-* annotation-list: Locating Annotations.
-* annotation-menu: Annotation Properties.
-* annotation-side: Annotation Properties.
-* annotation-visible: Annotation Properties.
-* annotation-width: Annotation Properties.
-* annotationp: Annotation Primitives.
-* annotations-at: Locating Annotations.
-* annotations-in-region: Locating Annotations.
-* anonymous function: Anonymous Functions.
-* anonymous lambda expressions (Edebug): Instrumenting.
-* apostrophe for quoting: Quoting.
-* append: Building Lists.
-* append-to-file: Writing to Files.
-* apply: Calling Functions.
-* apply, and debugging: Internals of Debugger.
-* apropos: Help Functions.
-* aref: Array Functions.
-* argument binding: Argument List.
-* argument descriptors: Using Interactive.
-* argument evaluation form: Using Interactive.
-* argument prompt: Using Interactive.
-* arguments, reading: Minibuffers.
-* arith-error example: Handling Errors.
-* arith-error in division: Arithmetic Operations.
-* arithmetic shift: Bitwise Operations.
-* array: Arrays.
-* array elements: Array Functions.
-* arrayp: Array Functions.
-* ASCII character codes: Character Type.
-* aset: Array Functions.
-* ash: Bitwise Operations.
-* asin: Math Functions.
-* asinh: Math Functions.
-* ask-user-about-lock: File Locks.
-* ask-user-about-supersession-threat: Modification Time.
-* asking the user questions: Yes-or-No Queries.
-* assoc: Association Lists.
-* association list: Association Lists.
-* assq: Association Lists.
-* asynchronous subprocess: Asynchronous Processes.
-* atan: Math Functions.
-* atanh: Math Functions.
-* atom <1>: List-related Predicates.
-* atom: Cons Cell Type.
-* atomic extent: Atomic Extents.
-* atoms: List-related Predicates.
-* attributes of text: Text Properties.
-* Auto Fill mode: Auto Filling.
-* auto-fill-function: Auto Filling.
-* auto-lower-frame: Raising and Lowering.
-* auto-mode-alist: Auto Major Mode.
-* auto-raise-frame: Raising and Lowering.
-* auto-save-default: Auto-Saving.
-* auto-save-file-format: Format Conversion.
-* auto-save-file-name-p: Auto-Saving.
-* auto-save-hook: Auto-Saving.
-* auto-save-interval: Auto-Saving.
-* auto-save-list-file-name: Auto-Saving.
-* auto-save-mode: Auto-Saving.
-* auto-save-timeout: Auto-Saving.
-* auto-save-visited-file-name: Auto-Saving.
-* auto-saving: Auto-Saving.
-* autoload <1>: Domain Specification.
-* autoload: Autoload.
-* autoload errors: Autoload.
-* automatically buffer-local: Intro to Buffer-Local.
-* available fonts: Font Instance Names.
-* back-to-indentation: Motion by Indent.
-* background pixmap: Merging Faces.
-* backquote (Edebug): Debugging Backquote.
-* backquote (list substitution): Backquote.
-* backslash in character constant: Character Type.
-* backslash in strings: String Type.
-* backslash in symbols: Symbol Type.
-* backspace: Character Type.
-* backtrace: Internals of Debugger.
-* backtrace-debug: Internals of Debugger.
-* backtrace-frame: Internals of Debugger.
-* backtracking: Backtracking.
-* backup file: Backup Files.
-* backup files, how to make them: Rename or Copy.
-* backup-buffer: Making Backups.
-* backup-by-copying: Rename or Copy.
-* backup-by-copying-when-linked: Rename or Copy.
-* backup-by-copying-when-mismatch: Rename or Copy.
-* backup-enable-predicate: Making Backups.
-* backup-file-name-p: Backup Names.
-* backup-inhibited: Making Backups.
-* backward-char: Character Motion.
-* backward-delete-char-untabify: Deletion.
-* backward-list: List Motion.
-* backward-prefix-chars: Motion and Syntax.
-* backward-sexp: List Motion.
-* backward-to-indentation: Motion by Indent.
-* backward-word: Word Motion.
-* balancing parentheses: Blinking.
-* barf-if-buffer-read-only: Read Only Buffers.
-* base buffer: Indirect Buffers.
-* base64: Transformations.
-* base64-decode-region: Transformations.
-* base64-decode-string: Transformations.
-* base64-encode-region: Transformations.
-* base64-encode-string: Transformations.
-* batch mode: Batch Mode.
-* batch-byte-compile: Compilation Functions.
-* batch-byte-recompile-directory: Compilation Functions.
-* beep: Beeping.
-* beeping: Beeping.
-* before point, insertion: Insertion.
-* before-change-function: Change Hooks.
-* before-change-functions: Change Hooks.
-* before-init-hook: Init File.
-* before-revert-hook: Reverting.
-* beginning of line: Text Lines.
-* beginning of line in regexp: Syntax of Regexps.
-* beginning-of-buffer: Buffer End Motion.
-* beginning-of-defun: List Motion.
-* beginning-of-line: Text Lines.
-* bell: Beeping.
-* bell character: Character Type.
-* bell-volume: Beeping.
-* binary files and text files: Files and MS-DOS.
-* binary-process-input: MS-DOS Subprocesses.
-* binary-process-output: MS-DOS Subprocesses.
-* bind-text-domain: Level 3 Primitives.
-* binding arguments: Argument List.
-* binding local variables: Local Variables.
-* binding of a key: Keymap Terminology.
-* bit vector: Bit Vectors.
-* bit vector length: Sequence Functions.
-* bit-vector: Bit Vector Functions.
-* bit-vector-p: Bit Vector Functions.
-* bitp: Bit Vector Functions.
-* bitwise and: Bitwise Operations.
-* bitwise exclusive or: Bitwise Operations.
-* bitwise not: Bitwise Operations.
-* bitwise or: Bitwise Operations.
-* blink-matching-open: Blinking.
-* blink-matching-paren: Blinking.
-* blink-matching-paren-delay: Blinking.
-* blink-matching-paren-distance: Blinking.
-* blink-paren-function: Blinking.
-* blink-paren-hook: Blinking.
-* blinking: Blinking.
-* bobp: Near Point.
-* body of function: Lambda Components.
-* bold: Font Instance Characteristics.
-* bolp: Near Point.
-* bookmark-map: Standard Keymaps.
-* boolean: nil and t.
-* boolean-specifier-p: Specifier Types.
-* bootstrapping XEmacs from temacs: Building XEmacs.
-* bottom-toolbar: Specifying the Toolbar.
-* bottom-toolbar-height: Other Toolbar Variables.
-* bottom-toolbar-visible-p: Other Toolbar Variables.
-* boundp: Void Variables.
-* box diagrams, for lists: Cons Cell Type.
-* box representation for lists: Lists as Boxes.
-* break: Debugger.
-* breakpoints: Breakpoints.
-* bucket (in obarray): Creating Symbols.
-* buffer: Buffers.
-* buffer contents: Text.
-* buffer file name: Buffer File Name.
-* buffer input stream: Input Streams.
-* buffer list: The Buffer List.
-* buffer modification: Buffer Modification.
-* buffer names: Buffer Names.
-* buffer output stream: Output Streams.
-* buffer text notation: Buffer Text Notation.
-* buffer, read-only: Read Only Buffers.
-* buffer-auto-save-file-name: Auto-Saving.
-* buffer-backed-up: Making Backups.
-* buffer-base-buffer: Indirect Buffers.
-* buffer-disable-undo: Maintaining Undo.
-* buffer-enable-undo: Maintaining Undo.
-* buffer-end: Point.
-* buffer-file-format: Format Conversion.
-* buffer-file-name: Buffer File Name.
-* buffer-file-number: Buffer File Name.
-* buffer-file-truename: Buffer File Name.
-* buffer-file-type: Files and MS-DOS.
-* buffer-flush-undo: Maintaining Undo.
-* buffer-glyph-p: Glyph Types.
-* buffer-indirect-children: Indirect Buffers.
-* buffer-invisibility-spec: Invisible Text.
-* buffer-list: The Buffer List.
-* buffer-live-p: Killing Buffers.
-* buffer-local variables: Buffer-Local Variables.
-* buffer-local variables in modes: Major Mode Conventions.
-* buffer-local-variables: Creating Buffer-Local.
-* Buffer-menu-mode-map: Standard Keymaps.
-* buffer-modified-p: Buffer Modification.
-* buffer-modified-tick: Buffer Modification.
-* buffer-name: Buffer Names.
-* buffer-offer-save <1>: Killing Buffers.
-* buffer-offer-save: Saving Buffers.
-* buffer-read-only: Read Only Buffers.
-* buffer-saved-size <1>: Point.
-* buffer-saved-size: Auto-Saving.
-* buffer-size: Point.
-* buffer-string: Buffer Contents.
-* buffer-substring: Buffer Contents.
-* buffer-undo-list: Undo.
-* bufferp: Buffer Basics.
-* buffers menu: Buffers Menu.
-* buffers, controlled in windows: Buffers and Windows.
-* buffers, creating: Creating Buffers.
-* buffers, killing: Killing Buffers.
-* buffers-menu-filter: Menu Filters.
-* buffers-menu-max-size: Buffers Menu.
-* buffers-menu-switch-to-buffer-function: Buffers Menu.
-* building lists: Building Lists.
-* building XEmacs: Building XEmacs.
-* built-in function: What Is a Function.
-* bury-buffer: The Buffer List.
-* busy-pointer-glyph: Mouse Pointer.
-* button-event-p: Event Predicates.
-* button-press-event-p: Event Predicates.
-* button-release-event-p: Event Predicates.
-* bvconcat: Bit Vector Functions.
-* byte-code <1>: Compilation Functions.
-* byte-code: Byte Compilation.
-* byte-code function: Compiled-Function Objects.
-* byte-code interpreter: Compilation Functions.
-* byte-compile: Compilation Functions.
-* byte-compile-dynamic: Dynamic Loading.
-* byte-compile-dynamic-docstrings: Docs and Compilation.
-* byte-compile-file: Compilation Functions.
-* byte-compiling macros: Compiling Macros.
-* byte-compiling require: Named Features.
-* byte-recompile-directory: Compilation Functions.
-* byte-recompile-directory-ignore-errors-p: Compilation Functions.
-* bytes: Strings and Characters.
-* c++-mode-map: Standard Keymaps.
-* C-c: Prefix Keys.
-* C-g: Quitting.
-* C-h: Prefix Keys.
-* C-M-x: Instrumenting.
-* c-mode-abbrev-table: Standard Abbrev Tables.
-* c-mode-map: Standard Keymaps.
-* c-mode-syntax-table: Standard Syntax Tables.
-* C-q: Flow Control.
-* C-s: Flow Control.
-* C-x: Prefix Keys.
-* C-x 4: Prefix Keys.
-* C-x 5: Prefix Keys.
-* C-x a: Prefix Keys.
-* C-x n: Prefix Keys.
-* C-x r: Prefix Keys.
-* caaaar: List Elements.
-* caaadr: List Elements.
-* caaar: List Elements.
-* caadar: List Elements.
-* caaddr: List Elements.
-* caadr: List Elements.
-* caar: List Elements.
-* cadaar: List Elements.
-* cadadr: List Elements.
-* cadar: List Elements.
-* caddar: List Elements.
-* cadddr: List Elements.
-* caddr: List Elements.
-* cadr: List Elements.
-* call stack: Internals of Debugger.
-* call-interactively: Interactive Call.
-* call-process: Synchronous Processes.
-* call-process-region: Synchronous Processes.
-* calling a function: Calling Functions.
-* cancel-debug-on-entry: Function Debugging.
-* canonicalize-inst-list: Adding Specifications.
-* canonicalize-inst-pair: Adding Specifications.
-* canonicalize-lax-plist: Working With Lax Plists.
-* canonicalize-plist: Working With Normal Plists.
-* canonicalize-spec: Adding Specifications.
-* canonicalize-spec-list: Adding Specifications.
-* canonicalize-tag-set: Specifier Tag Functions.
-* capitalization: Character Case.
-* capitalize: Character Case.
-* capitalize-region: Case Changes.
-* capitalize-word: Case Changes.
-* car: List Elements.
-* car-safe: List Elements.
-* case changes: Case Changes.
-* case in replacements: Replacing Match.
-* case-fold-search: Searching and Case.
-* case-replace: Searching and Case.
-* case-table-p: Case Tables.
-* catch: Catch and Throw.
-* category-designator-p: Category Tables.
-* category-table: Category Tables.
-* category-table-p: Category Tables.
-* category-table-value-p: Category Tables.
-* CBREAK: Flow Control.
-* ccl-elapsed-time: Calling CCL.
-* ccl-execute: Calling CCL.
-* ccl-execute-on-string: Calling CCL.
-* ccl-reset-elapsed-time: Calling CCL.
-* cdaaar: List Elements.
-* cdaadr: List Elements.
-* cdaar: List Elements.
-* cdadar: List Elements.
-* cdaddr: List Elements.
-* cdadr: List Elements.
-* cdar: List Elements.
-* cddaar: List Elements.
-* cddadr: List Elements.
-* cddar: List Elements.
-* cdddar: List Elements.
-* cddddr: List Elements.
-* cdddr: List Elements.
-* cddr: List Elements.
-* CDE dt: CDE dt.
-* cdr: List Elements.
-* cdr-safe: List Elements.
-* ceiling: Numeric Conversions.
-* centering point: Vertical Scrolling.
-* cerror: Signaling Errors.
-* change hooks: Change Hooks.
-* change-major-mode-hook: Major Mode Conventions.
-* changing key bindings: Changing Key Bindings.
-* changing to another buffer: Current Buffer.
-* changing window size: Resizing Windows.
-* char table type: Char Table Type.
-* char-after: Near Point.
-* char-before: Near Point.
-* char-charset: MULE Characters.
-* char-equal: Text Comparison.
-* char-int: Character Codes.
-* char-int confoundance disease: Character Type.
-* char-int-p: Character Codes.
-* char-octet: MULE Characters.
-* char-or-char-int-p: Character Codes.
-* char-or-string-p: Predicates for Strings.
-* char-syntax: Syntax Table Functions.
-* char-table-p: Char Tables.
-* char-table-type: Char Table Types.
-* char-table-type-list: Char Table Types.
-* char-to-string: String Conversion.
-* char=: Text Comparison.
-* character arrays: Strings and Characters.
-* character case: Character Case.
-* character descriptor: Character Descriptors.
-* character insertion: Commands for Insertion.
-* character printing: Describing Characters.
-* character set (in regexp): Syntax of Regexps.
-* character to string: String Conversion.
-* character-to-event: Converting Events.
-* characteristics of font instances: Font Instance Characteristics.
-* characterp: Predicates for Characters.
-* characters: Strings and Characters.
-* characters for interactive codes: Interactive Codes.
-* character quote: Syntax Class Table.
-* charset type: Charset Type.
-* charset-ccl-program: Charset Property Functions.
-* charset-chars: Charset Property Functions.
-* charset-columns: Charset Property Functions.
-* charset-dimension: Charset Property Functions.
-* charset-direction: Charset Property Functions.
-* charset-doc-string: Charset Property Functions.
-* charset-final: Charset Property Functions.
-* charset-from-attributes: Basic Charset Functions.
-* charset-graphic: Charset Property Functions.
-* charset-list: Basic Charset Functions.
-* charset-name: Charset Property Functions.
-* charset-property: Charset Property Functions.
-* charset-registry: Charset Property Functions.
-* charset-reverse-direction-charset: Basic Charset Functions.
-* charsetp: Charsets.
-* check-argument-type: Signaling Errors.
-* check-toolbar-button-syntax: Toolbar Descriptor Format.
-* check-valid-char-table-value: Working With Char Tables.
-* check-valid-inst-list: Specifier Validation Functions.
-* check-valid-instantiator: Specifier Validation Functions.
-* check-valid-plist: Property Lists.
-* check-valid-spec-list: Specifier Validation Functions.
-* child process: Processes.
-* children, of extent: Extent Parents.
-* CL note--allocate more storage: Garbage Collection.
-* CL note--case of letters: Symbol Type.
-* CL note--default optional arg: Argument List.
-* CL note--integers vrs eq: Comparison of Numbers.
-* CL note--lack union, set: Sets And Lists.
-* CL note--only throw in Emacs: Catch and Throw.
-* CL note--rplaca vrs setcar: Modifying Lists.
-* CL note--set local: Setting Variables.
-* CL note--special forms compared: Special Forms.
-* CL note--special variables: Variable Scoping.
-* CL note--symbol in obarrays: Creating Symbols.
-* cl-read: Reading in Edebug.
-* cl-specs.el: Instrumenting.
-* cl.el (Edebug): Instrumenting.
-* cleanup forms: Cleanups.
-* clear-abbrev-table: Abbrev Tables.
-* clear-message: The Echo Area.
-* clear-range-table: Working With Range Tables.
-* clear-visited-file-modtime: Modification Time.
-* close parenthesis: Blinking.
-* close-database: Connecting to a Database.
-* close parenthesis character: Syntax Class Table.
-* closures not available: Extent.
-* clrhash: Working With Hash Tables.
-* codes, interactive, description of: Interactive Codes.
-* coding standards: Tips.
-* coding system type: Coding System Type.
-* coding-category-list: Detection of Textual Encoding.
-* coding-category-system: Detection of Textual Encoding.
-* coding-priority-list: Detection of Textual Encoding.
-* coding-system-doc-string: Coding System Property Functions.
-* coding-system-list: Basic Coding System Functions.
-* coding-system-name: Basic Coding System Functions.
-* coding-system-p: Coding Systems.
-* coding-system-property: Coding System Property Functions.
-* coding-system-type: Coding System Property Functions.
-* color instance type: Color Instance Type.
-* color instances: Color Instances.
-* color-instance-name: Color Instance Properties.
-* color-instance-p: Color Instances.
-* color-instance-rgb-components: Color Instance Properties.
-* color-name: Color Convenience Functions.
-* color-pixmap-image-instance-p: Image Instance Types.
-* color-rgb-components: Color Convenience Functions.
-* color-specifier-p <1>: Color Specifiers.
-* color-specifier-p: Specifier Types.
-* colorize-image-instance: Image Instance Functions.
-* colors: Colors.
-* columns: Columns.
-* command: What Is a Function.
-* command descriptions: A Sample Function Description.
-* command history: Command History.
-* command in keymap: Key Lookup.
-* command line arguments: Command Line Arguments.
-* command line options: Command Line Arguments.
-* command loop: Command Loop.
-* command loop, recursive: Recursive Editing.
-* command-debug-status: Internals of Debugger.
-* command-execute: Interactive Call.
-* command-history: Command History.
-* command-history-map: Standard Keymaps.
-* command-line: Command Line Arguments.
-* command-line-args: Command Line Arguments.
-* command-line-functions: Command Line Arguments.
-* command-line-processed: Command Line Arguments.
-* command-switch-alist: Command Line Arguments.
-* commandp: Interactive Call.
-* commandp example: High-Level Completion.
-* commands, defining: Defining Commands.
-* comment syntax: Syntax Class Table.
-* comments: Comments.
-* comment ender: Syntax Class Table.
-* comment starter: Syntax Class Table.
-* Common Lisp: Lisp History.
-* Common Lisp (Edebug): Instrumenting.
-* compare-buffer-substrings: Comparing Text.
-* comparing buffer text: Comparing Text.
-* comparison of modification time: Modification Time.
-* compilation: Byte Compilation.
-* compilation functions: Compilation Functions.
-* compile-defun: Compilation Functions.
-* compiled function: Compiled-Function Objects.
-* compiled-function-arglist: Compiled-Function Objects.
-* compiled-function-constants: Compiled-Function Objects.
-* compiled-function-doc-string: Compiled-Function Objects.
-* compiled-function-domain: Compiled-Function Objects.
-* compiled-function-instructions: Compiled-Function Objects.
-* compiled-function-interactive: Compiled-Function Objects.
-* compiled-function-p: What Is a Function.
-* compiled-function-stack-size: Compiled-Function Objects.
-* complete key: Keymap Terminology.
-* completing-read: Minibuffer Completion.
-* completion: Completion.
-* completion, file name: File Name Completion.
-* completion, user name: User Name Completion.
-* completion-auto-help: Completion Commands.
-* completion-ignore-case: Basic Completion.
-* completion-ignored-extensions: File Name Completion.
-* complex arguments: Minibuffers.
-* complex command: Command History.
-* complex-buffers-menu-p: Buffers Menu.
-* compose-region: Composite Characters.
-* composite-char-string: Composite Characters.
-* concat: Creating Strings.
-* concatenating lists: Rearrangement.
-* concatenating strings: Creating Strings.
-* cond: Conditionals.
-* condition name: Error Symbols.
-* condition-case: Handling Errors.
-* conditional evaluation: Conditionals.
-* cons: Building Lists.
-* cons cell as box: Lists as Boxes.
-* cons cells: Building Lists.
-* consing: Building Lists.
-* console-device-list: Basic Console Functions.
-* console-disable-input: Console and Device I/O.
-* console-enable-input: Console and Device I/O.
-* console-list: Basic Console Functions.
-* console-live-p: Connecting to a Console or Device.
-* console-type-image-conversion-list: Image Instantiator Conversion.
-* consolep: Consoles and Devices.
-* consoles: Consoles and Devices.
-* consp: List-related Predicates.
-* continuation lines: Truncation.
-* continuation-glyph: Redisplay Glyphs.
-* continue-process: Signals to Processes.
-* control character printing: Describing Characters.
-* control characters: Character Type.
-* control characters in display: Usual Display.
-* control characters, reading: Quoted Character Input.
-* control structures: Control Structures.
-* control-arrow-glyph: Redisplay Glyphs.
-* Control-X-prefix: Prefix Keys.
-* conventions for writing minor modes: Minor Mode Conventions.
-* conversion of image instantiators: Image Instantiator Conversion.
-* conversion of strings: String Conversion.
-* copy-alist: Association Lists.
-* copy-category-table: Category Tables.
-* copy-coding-system: Basic Coding System Functions.
-* copy-event: Working With Events.
-* copy-extent: Detached Extents.
-* copy-face: Basic Face Functions.
-* copy-file: Changing File Attributes.
-* copy-hash-table: Introduction to Hash Tables.
-* copy-keymap: Creating Keymaps.
-* copy-marker: Creating Markers.
-* copy-range-table: Introduction to Range Tables.
-* copy-region-as-kill: Kill Functions.
-* copy-sequence: Sequence Functions.
-* copy-specifier: Other Specification Functions.
-* copy-syntax-table: Syntax Table Functions.
-* copying alists: Association Lists.
-* copying bit vectors: Bit Vector Functions.
-* copying files: Changing File Attributes.
-* copying lists: Building Lists.
-* copying sequences: Sequence Functions.
-* copying strings: Creating Strings.
-* copying vectors: Vector Functions.
-* cos: Math Functions.
-* cosh: Math Functions.
-* count-lines: Text Lines.
-* count-loop: A Sample Function Description.
-* counting columns: Columns.
-* coverage testing: Coverage Testing.
-* create-device-hook: Connecting to a Console or Device.
-* create-file-buffer: Subroutines of Visiting.
-* create-frame-hook: Frame Hooks.
-* create-tooltalk-message: Elisp Interface for Sending Messages.
-* create-tooltalk-pattern: Elisp Interface for Receiving Messages.
-* creating buffers: Creating Buffers.
-* creating keymaps: Creating Keymaps.
-* ctl-arrow: Usual Display.
-* ctl-x-4-map <1>: Standard Keymaps.
-* ctl-x-4-map: Prefix Keys.
-* ctl-x-5-map <1>: Standard Keymaps.
-* ctl-x-5-map: Prefix Keys.
-* ctl-x-map <1>: Standard Keymaps.
-* ctl-x-map: Prefix Keys.
-* cube-root: Math Functions.
-* current binding: Local Variables.
-* current buffer: Current Buffer.
-* current buffer excursion: Excursions.
-* current buffer mark: The Mark.
-* current buffer point and mark (Edebug): Edebug Display Update.
-* current buffer position: Point.
-* current command: Command Loop Info.
-* current stack frame: Using Debugger.
-* current-buffer: Current Buffer.
-* current-case-table: Case Tables.
-* current-column: Columns.
-* current-fill-column: Margins.
-* current-frame-configuration: Frame Configurations.
-* current-global-map: Active Keymaps.
-* current-indentation: Primitive Indent.
-* current-input-mode: Input Modes.
-* current-justification: Filling.
-* current-keymaps: Active Keymaps.
-* current-kill: Low-Level Kill Ring.
-* current-left-margin: Margins.
-* current-local-map: Active Keymaps.
-* current-menubar: Menubar.
-* current-message: The Echo Area.
-* current-minor-mode-maps: Active Keymaps.
-* current-mouse-event: Command Loop Info.
-* current-prefix-arg: Prefix Command Arguments.
-* current-time: Time of Day.
-* current-time-string: Time of Day.
-* current-time-zone: Time of Day.
-* current-window-configuration: Window Configurations.
-* cursor (mouse): Mouse Pointer.
-* cursor-in-echo-area: The Echo Area.
-* cust-print: Printing in Edebug.
-* cut buffer: X Selections.
-* cyclic ordering of windows: Cyclic Window Ordering.
-* data type: Lisp Data Types.
-* data-directory: Accessing Documentation.
-* database: Databases.
-* database type: Database Type.
-* database-file-name: Other Database Functions.
-* database-last-error: Other Database Functions.
-* database-live-p: Connecting to a Database.
-* database-subtype: Other Database Functions.
-* database-type: Other Database Functions.
-* databasep: Databases.
-* deallocate-event: Working With Events.
-* debug: Invoking the Debugger.
-* debug-allocation: Garbage Collection.
-* debug-allocation-backtrace: Garbage Collection.
-* debug-ignored-errors: Error Debugging.
-* debug-on-entry: Function Debugging.
-* debug-on-error: Error Debugging.
-* debug-on-error use: Processing of Errors.
-* debug-on-next-call: Internals of Debugger.
-* debug-on-quit: Infinite Loops.
-* debug-on-signal: Error Debugging.
-* debug-on-signal use: Handling Errors.
-* debugger <1>: Internals of Debugger.
-* debugger: Debugger.
-* debugger command list: Debugger Commands.
-* debugger-mode-map: Standard Keymaps.
-* debugging errors: Error Debugging.
-* debugging specific functions: Function Debugging.
-* decode-big5-char: Big5 and Shift-JIS Functions.
-* decode-coding-region: Encoding and Decoding Text.
-* decode-shift-jis-char: Big5 and Shift-JIS Functions.
-* decode-time: Time Conversion.
-* decoding file formats: Format Conversion.
-* decompose-region: Composite Characters.
-* decrement field of register: Cons Cell Type.
-* dedicated window: Choosing Window.
-* deep binding: Impl of Scope.
-* def-edebug-spec: Instrumenting Macro Calls.
-* defalias: Defining Functions.
-* default argument string: Interactive Codes.
-* default init file: Init File.
-* default value: Default Value.
-* default-abbrev-mode: Abbrev Mode.
-* default-boundp: Default Value.
-* default-buffer-file-type: Files and MS-DOS.
-* default-case-fold-search: Searching and Case.
-* default-ctl-arrow: Usual Display.
-* default-deselect-frame-hook: Raising and Lowering.
-* default-directory: File Name Expansion.
-* default-file-modes: Changing File Attributes.
-* default-fill-column: Margins.
-* default-frame-name: Frame Name.
-* default-frame-plist: Initial Properties.
-* default-justification: Filling.
-* default-major-mode: Auto Major Mode.
-* default-menubar: Menubar.
-* default-minibuffer-frame: Minibuffers and Frames.
-* default-modeline-format: Modeline Variables.
-* default-popup-menu: Pop-Up Menus.
-* default-select-frame-hook: Raising and Lowering.
-* default-text-properties: Examining Properties.
-* default-toolbar: Specifying the Toolbar.
-* default-toolbar-height: Other Toolbar Variables.
-* default-toolbar-position: Specifying the Toolbar.
-* default-toolbar-visible-p: Other Toolbar Variables.
-* default-toolbar-width: Other Toolbar Variables.
-* default-truncate-lines: Truncation.
-* default-value: Default Value.
-* default-x-device: Resources.
-* default.el: Start-up Summary.
-* defconst <1>: Domain Specification.
-* defconst: Defining Variables.
-* defcustom: Variable Definitions.
-* defgroup: Group Definitions.
-* define-abbrev: Defining Abbrevs.
-* define-abbrev-table: Abbrev Tables.
-* define-derived-mode: Derived Modes.
-* define-error: Error Symbols.
-* define-function: Defining Functions.
-* define-key: Changing Key Bindings.
-* define-logical-name: Changing File Attributes.
-* define-obsolete-function-alias: Obsoleteness.
-* define-obsolete-variable-alias: Obsoleteness.
-* define-prefix-command: Prefix Keys.
-* define-specifier-tag: Specifier Tag Functions.
-* defining a function: Defining Functions.
-* defining commands: Defining Commands.
-* defining-kbd-macro: Keyboard Macros.
-* definition of a symbol: Definitions.
-* defmacro: Defining Macros.
-* defsubst: Inline Functions.
-* defun: Defining Functions.
-* defun-prompt-regexp: List Motion.
-* defvar <1>: Domain Specification.
-* defvar: Defining Variables.
-* defvaralias: Variable Aliases.
-* deiconify-frame: Visibility of Frames.
-* delete: Sets And Lists.
-* delete previous char: Deletion.
-* delete-annotation: Annotation Primitives.
-* delete-auto-save-file-if-necessary: Auto-Saving.
-* delete-auto-save-files: Auto-Saving.
-* delete-backward-char: Deletion.
-* delete-blank-lines: User-Level Deletion.
-* delete-char: Deletion.
-* delete-device: Connecting to a Console or Device.
-* delete-device-hook: Connecting to a Console or Device.
-* delete-directory: Create/Delete Dirs.
-* delete-exited-processes: Deleting Processes.
-* delete-extent: Creating and Modifying Extents.
-* delete-file: Changing File Attributes.
-* delete-frame: Deleting Frames.
-* delete-frame-hook: Frame Hooks.
-* delete-horizontal-space: User-Level Deletion.
-* delete-indentation: User-Level Deletion.
-* delete-menu-item: Modifying Menus.
-* delete-old-versions: Numbered Backups.
-* delete-other-windows: Deleting Windows.
-* delete-process: Deleting Processes.
-* delete-region: Deletion.
-* delete-to-left-margin: Margins.
-* delete-window: Deleting Windows.
-* delete-windows-on: Deleting Windows.
-* deleting files: Changing File Attributes.
-* deleting processes: Deleting Processes.
-* deleting whitespace: User-Level Deletion.
-* deleting windows: Deleting Windows.
-* deletion of elements: Sets And Lists.
-* deletion of frames: Deleting Frames.
-* deletion vs killing: Deletion.
-* delq: Sets And Lists.
-* demibold: Font Instance Characteristics.
-* describe-bindings: Scanning Keymaps.
-* describe-bindings-internal: Scanning Keymaps.
-* describe-buffer-case-table: Case Tables.
-* describe-mode: Mode Help.
-* describe-prefix-bindings: Help Functions.
-* describe-tooltalk-message: Elisp Interface for Receiving Messages.
-* description for interactive codes: Interactive Codes.
-* description format: Format of Descriptions.
-* deselect-frame-hook: Frame Hooks.
-* destroy-tooltalk-message: Elisp Interface for Sending Messages.
-* destroy-tooltalk-pattern: Elisp Interface for Receiving Messages.
-* destructive-alist-to-plist: Converting Plists To/From Alists.
-* destructive-plist-to-alist: Converting Plists To/From Alists.
-* detach-extent: Detached Extents.
-* detached extent: Detached Extents.
-* detect-coding-region: Detection of Textual Encoding.
-* device-baud-rate <1>: Terminal Output.
-* device-baud-rate: Console and Device I/O.
-* device-class: Console Types and Device Classes.
-* device-frame-list <1>: Basic Device Functions.
-* device-frame-list: Finding All Frames.
-* device-list: Basic Device Functions.
-* device-live-p: Connecting to a Console or Device.
-* device-matches-specifier-tag-set-p: Specifier Tag Functions.
-* device-matching-specifier-tag-list: Specifier Tag Functions.
-* device-or-frame-p: Basic Device Functions.
-* device-or-frame-type: Console Types and Device Classes.
-* device-type: Console Types and Device Classes.
-* device-x-display: Connecting to a Console or Device.
-* devicep: Consoles and Devices.
-* devices: Consoles and Devices.
-* dgettext: Level 3 Primitives.
-* diagrams, boxed, for lists: Cons Cell Type.
-* dialog box: Dialog Boxes.
-* digit-argument: Prefix Command Arguments.
-* ding: Beeping.
-* directory name: Directory Names.
-* directory name abbreviation: Directory Names.
-* directory part (of file name): File Name Components.
-* directory-abbrev-alist: Directory Names.
-* directory-file-name: Directory Names.
-* directory-files: Contents of Directories.
-* directory-oriented functions: Contents of Directories.
-* dired-kept-versions: Numbered Backups.
-* dired-mode-map: Standard Keymaps.
-* disable undo: Maintaining Undo.
-* disable-command: Disabling Commands.
-* disable-menu-item: Modifying Menus.
-* disable-timeout: Timers.
-* disabled: Disabling Commands.
-* disabled command: Disabling Commands.
-* disabled-command-hook: Disabling Commands.
-* disassemble: Disassembly.
-* disassembled byte-code: Disassembly.
-* discard input: Peeking and Discarding.
-* discard-input: Peeking and Discarding.
-* dispatch-event: Dispatching an Event.
-* dispatching an event: Dispatching an Event.
-* display columns: Size and Position.
-* display lines: Size and Position.
-* display order: Extent Endpoints.
-* display table: Display Tables.
-* display update: Refresh Screen.
-* display-buffer: Choosing Window.
-* display-buffer-function: Choosing Window.
-* display-completion-list: Completion Commands.
-* display-error: Processing of Errors.
-* display-message: The Echo Area.
-* display-warning: Warnings.
-* display-warning-minimum-level: Warnings.
-* display-warning-suppressed-classes: Warnings.
-* displaying a buffer: Displaying Buffers.
-* do-auto-save: Auto-Saving.
-* DOC (documentation) file: Documentation Basics.
-* doc-directory: Accessing Documentation.
-* documentation: Accessing Documentation.
-* documentation conventions: Documentation Basics.
-* documentation for major mode: Mode Help.
-* documentation notation: Evaluation Notation.
-* documentation of function: Function Documentation.
-* documentation strings: Documentation.
-* documentation, keys in: Keys in Documentation.
-* documentation-property: Accessing Documentation.
-* domain: Level 3 Primitives.
-* domain (in a specifier): Specifiers In-Depth.
-* domain-of: Level 3 Primitives.
-* dotted lists (Edebug): Specification List.
-* dotted pair notation: Dotted Pair Notation.
-* double-quote in strings: String Type.
-* down-list: List Motion.
-* downcase: Character Case.
-* downcase-region: Case Changes.
-* downcase-word: Case Changes.
-* downcasing in lookup-key: Key Sequence Input.
-* drag: Drag Interface.
-* drag and drop: Drag and Drop.
-* Drag API: Drag Interface.
-* dribble file: Recording Input.
-* drop: Drop Interface.
-* Drop API: Drop Interface.
-* dump-emacs: Building XEmacs.
-* duplicable extent: Duplicable Extents.
-* dynamic loading of documentation: Docs and Compilation.
-* dynamic loading of functions: Dynamic Loading.
-* dynamic scoping: Variable Scoping.
-* echo area: The Echo Area.
-* echo-keystrokes <1>: The Echo Area.
-* echo-keystrokes: Command Loop Info.
-* edebug: Embedded Breakpoints.
-* Edebug: Edebug.
-* Edebug execution modes: Edebug Execution Modes.
-* Edebug mode: Edebug.
-* Edebug specification list: Specification List.
-* edebug-`: Debugging Backquote.
-* edebug-all-defs <1>: Edebug Options.
-* edebug-all-defs: Instrumenting.
-* edebug-all-forms <1>: Edebug Options.
-* edebug-all-forms: Instrumenting.
-* edebug-continue-kbd-macro: Edebug Options.
-* edebug-display-freq-count: Coverage Testing.
-* edebug-eval-top-level-form: Instrumenting.
-* edebug-global-break-condition <1>: Edebug Options.
-* edebug-global-break-condition: Global Break Condition.
-* edebug-initial-mode: Edebug Options.
-* edebug-on-error <1>: Edebug Options.
-* edebug-on-error: Trapping Errors.
-* edebug-on-quit <1>: Edebug Options.
-* edebug-on-quit: Trapping Errors.
-* edebug-print-circle <1>: Edebug Options.
-* edebug-print-circle: Printing in Edebug.
-* edebug-print-length <1>: Edebug Options.
-* edebug-print-length: Printing in Edebug.
-* edebug-print-level <1>: Edebug Options.
-* edebug-print-level: Printing in Edebug.
-* edebug-print-trace-after <1>: Edebug Options.
-* edebug-print-trace-after: Tracing.
-* edebug-print-trace-before <1>: Edebug Options.
-* edebug-print-trace-before: Tracing.
-* edebug-save-displayed-buffer-points <1>: Edebug Options.
-* edebug-save-displayed-buffer-points: Edebug Display Update.
-* edebug-save-windows <1>: Edebug Options.
-* edebug-save-windows: Edebug Display Update.
-* edebug-set-global-break-condition: Global Break Condition.
-* edebug-setup-hook: Edebug Options.
-* edebug-test-coverage: Edebug Options.
-* edebug-trace <1>: Edebug Options.
-* edebug-trace: Tracing.
-* edebug-tracing: Tracing.
-* edebug-unwrap: Specification List.
-* edebug-unwrap-results <1>: Edebug Options.
-* edebug-unwrap-results: Debugging Backquote.
-* edit-abbrevs-map: Standard Keymaps.
-* edit-and-eval-command: Object from Minibuffer.
-* edit-menu-filter: Menu Filters.
-* edit-tab-stops-map: Standard Keymaps.
-* editing types: Editing Types.
-* editor command loop: Command Loop.
-* eighth: List Elements.
-* electric-buffer-menu-mode-map: Standard Keymaps.
-* electric-future-map: A Sample Variable Description.
-* electric-history-map: Standard Keymaps.
-* element (of list): Lists.
-* elements of sequences: Sequence Functions.
-* elt: Sequence Functions.
-* emacs-build-time: Building XEmacs.
-* emacs-lisp-mode-map: Standard Keymaps.
-* emacs-lisp-mode-syntax-table: Standard Syntax Tables.
-* emacs-major-version: Building XEmacs.
-* emacs-minor-version: Building XEmacs.
-* emacs-pid: System Environment.
-* emacs-version: Building XEmacs.
-* EMACSLOADPATH environment variable: How Programs Do Loading.
-* embedded breakpoints: Embedded Breakpoints.
-* empty list: Cons Cell Type.
-* enable-command: Disabling Commands.
-* enable-flow-control: Flow Control.
-* enable-flow-control-on: Flow Control.
-* enable-local-eval: Auto Major Mode.
-* enable-local-variables: Auto Major Mode.
-* enable-menu-item: Modifying Menus.
-* enable-recursive-minibuffers: Minibuffer Misc.
-* encode-big5-char: Big5 and Shift-JIS Functions.
-* encode-coding-region: Encoding and Decoding Text.
-* encode-shift-jis-char: Big5 and Shift-JIS Functions.
-* encode-time: Time Conversion.
-* encoding file formats: Format Conversion.
-* end of buffer marker: Creating Markers.
-* end-of-buffer: Buffer End Motion.
-* end-of-defun: List Motion.
-* end-of-file: Input Functions.
-* end-of-line: Text Lines.
-* enlarge-window: Resizing Windows.
-* enlarge-window-horizontally: Resizing Windows.
-* enlarge-window-pixels: Resizing Windows.
-* enqueue-eval-event: Reading One Event.
-* environment: Intro Eval.
-* environment variable access: System Environment.
-* environment variables, subprocesses: Subprocess Creation.
-* eobp: Near Point.
-* eolp: Near Point.
-* eq: Equality Predicates.
-* equal: Equality Predicates.
-* equality: Equality Predicates.
-* erase-buffer: Deletion.
-* error: Signaling Errors.
-* error cleanup: Cleanups.
-* error debugging: Error Debugging.
-* error display: The Echo Area.
-* error handler: Handling Errors.
-* error in debug: Invoking the Debugger.
-* error message notation: Error Messages.
-* error name: Error Symbols.
-* error symbol: Error Symbols.
-* error-conditions: Error Symbols.
-* error-message-string: Processing of Errors.
-* errors: Errors.
-* esc-map: Prefix Keys.
-* ESC-prefix: Prefix Keys.
-* escape <1>: Syntax Class Table.
-* escape: Character Type.
-* escape characters: Output Variables.
-* escape characters in printing: Output Functions.
-* escape sequence: Character Type.
-* eval: Eval.
-* eval, and debugging: Internals of Debugger.
-* eval-and-compile: Eval During Compile.
-* eval-buffer: Eval.
-* eval-current-buffer (Edebug): Instrumenting.
-* eval-defun (Edebug): Instrumenting.
-* eval-event-p: Event Predicates.
-* eval-expression (Edebug): Instrumenting.
-* eval-minibuffer: Object from Minibuffer.
-* eval-region: Eval.
-* eval-region (Edebug): Instrumenting.
-* eval-when-compile: Eval During Compile.
-* evaluated expression argument: Interactive Codes.
-* evaluation: Evaluation.
-* evaluation error: Local Variables.
-* evaluation list (Edebug): Eval List.
-* evaluation notation: Evaluation Notation.
-* evaluation of buffer contents: Eval.
-* event printing: Describing Characters.
-* event-buffer: Window-Level Event Position Info.
-* event-button: Accessing Other Event Info.
-* event-closest-point: Event Text Position Info.
-* event-device: Accessing Other Event Info.
-* event-frame: Frame-Level Event Position Info.
-* event-function: Accessing Other Event Info.
-* event-glyph-extent: Event Glyph Position Info.
-* event-glyph-x-pixel: Event Glyph Position Info.
-* event-glyph-y-pixel: Event Glyph Position Info.
-* event-key: Accessing Other Event Info.
-* event-live-p: Event Predicates.
-* event-matches-key-specifier-p: Key Sequences.
-* event-modifier-bits: Accessing Other Event Info.
-* event-modifiers: Accessing Other Event Info.
-* event-object: Accessing Other Event Info.
-* event-over-border-p: Other Event Position Info.
-* event-over-glyph-p: Event Glyph Position Info.
-* event-over-modeline-p: Event Text Position Info.
-* event-over-text-area-p: Event Text Position Info.
-* event-over-toolbar-p: Event Toolbar Position Info.
-* event-point: Event Text Position Info.
-* event-process: Accessing Other Event Info.
-* event-timestamp: Accessing Other Event Info.
-* event-to-character: Converting Events.
-* event-toolbar-button: Event Toolbar Position Info.
-* event-type: Event Contents.
-* event-window: Window-Level Event Position Info.
-* event-window-x-pixel: Window-Level Event Position Info.
-* event-window-y-pixel: Window-Level Event Position Info.
-* event-x: Event Text Position Info.
-* event-x-pixel: Frame-Level Event Position Info.
-* event-y: Event Text Position Info.
-* event-y-pixel: Frame-Level Event Position Info.
-* eventp: Events.
-* events: Events.
-* events-to-keys: Converting Events.
-* examining windows: Buffers and Windows.
-* examples of using interactive: Interactive Examples.
-* exchange-point-and-mark: The Mark.
-* excursion: Excursions.
-* exec-directory: Subprocess Creation.
-* exec-path: Subprocess Creation.
-* execute program: Subprocess Creation.
-* execute with prefix argument: Interactive Call.
-* execute-extended-command: Interactive Call.
-* execute-kbd-macro: Keyboard Macros.
-* executing-macro: Keyboard Macros.
-* execution speed: Compilation Tips.
-* exit: Recursive Editing.
-* exit recursive editing: Recursive Editing.
-* exit-minibuffer: Minibuffer Misc.
-* exit-recursive-edit: Recursive Editing.
-* exiting XEmacs: Getting Out.
-* exp: Math Functions.
-* expand-abbrev: Abbrev Expansion.
-* expand-file-name: File Name Expansion.
-* expansion of file names: File Name Expansion.
-* expansion of macros: Expansion.
-* expression: Intro Eval.
-* expression prefix: Syntax Class Table.
-* expt: Math Functions.
-* extended-command-history: Minibuffer History.
-* extent <1>: Extents.
-* extent: Variable Scoping.
-* extent children: Extent Parents.
-* extent end position: Extent Endpoints.
-* extent endpoint: Extent Endpoints.
-* extent order: Extent Endpoints.
-* extent parent: Extent Parents.
-* extent priority: Intro to Extents.
-* extent property: Extent Properties.
-* extent replica: Duplicable Extents.
-* extent start position: Extent Endpoints.
-* extent, duplicable: Duplicable Extents.
-* extent, unique: Duplicable Extents.
-* extent-at: Finding Extents.
-* extent-begin-glyph: Extent Properties.
-* extent-begin-glyph-layout: Extent Properties.
-* extent-children: Extent Parents.
-* extent-descendants: Extent Parents.
-* extent-detached-p: Detached Extents.
-* extent-end-glyph: Extent Properties.
-* extent-end-glyph-layout: Extent Properties.
-* extent-end-position: Extent Endpoints.
-* extent-face: Extent Properties.
-* extent-in-region-p: Mapping Over Extents.
-* extent-keymap: Extent Properties.
-* extent-length: Extent Endpoints.
-* extent-list: Finding Extents.
-* extent-live-p: Creating and Modifying Extents.
-* extent-mouse-face: Extent Properties.
-* extent-object: Creating and Modifying Extents.
-* extent-parent: Extent Parents.
-* extent-priority: Extent Properties.
-* extent-properties: Extent Properties.
-* extent-property: Extent Properties.
-* extent-start-position: Extent Endpoints.
-* extentp: Extents.
-* extents, locating: Finding Extents.
-* extents, mapping: Mapping Over Extents.
-* face type: Face Type.
-* face-background: Face Convenience Functions.
-* face-background-instance: Face Convenience Functions.
-* face-background-pixmap: Face Convenience Functions.
-* face-background-pixmap-instance: Face Convenience Functions.
-* face-boolean-specifier-p: Specifier Types.
-* face-differs-from-default-p: Other Face Display Functions.
-* face-equal: Other Face Display Functions.
-* face-font: Face Convenience Functions.
-* face-font-instance: Face Convenience Functions.
-* face-font-name: Face Convenience Functions.
-* face-foreground: Face Convenience Functions.
-* face-foreground-instance: Face Convenience Functions.
-* face-list: Basic Face Functions.
-* face-property: Face Properties.
-* face-property-instance: Face Properties.
-* face-underline-p: Face Convenience Functions.
-* facep: Basic Face Functions.
-* faces: Faces and Window-System Objects.
-* fallback (in a specifier): Specifier Instancing.
-* false: nil and t.
-* fboundp: Function Cells.
-* fceiling: Rounding Operations.
-* featurep: Named Features.
-* features: Named Features.
-* fetch-bytecode: Dynamic Loading.
-* ffloor: Rounding Operations.
-* field width: Formatting Strings.
-* fifth: List Elements.
-* file accessibility: Testing Accessibility.
-* file age: Testing Accessibility.
-* file attributes: File Attributes.
-* file format conversion: Format Conversion.
-* file hard link: Changing File Attributes.
-* file locks: File Locks.
-* file mode specification error: Auto Major Mode.
-* file modes and MS-DOS: Changing File Attributes.
-* file modification time: Testing Accessibility.
-* file name completion subroutines: File Name Completion.
-* file name of buffer: Buffer File Name.
-* file name of directory: Directory Names.
-* file names: File Names.
-* file names in directory: Contents of Directories.
-* file open error: Subroutines of Visiting.
-* file symbolic links: Kinds of Files.
-* file types on MS-DOS: Files and MS-DOS.
-* file with multiple names: Changing File Attributes.
-* file-accessible-directory-p: Testing Accessibility.
-* file-already-exists: Changing File Attributes.
-* file-attributes: File Attributes.
-* file-directory-p: Kinds of Files.
-* file-error: How Programs Do Loading.
-* file-executable-p: Testing Accessibility.
-* file-exists-p: Testing Accessibility.
-* file-local-copy: Magic File Names.
-* file-locked: File Locks.
-* file-locked-p: File Locks.
-* file-menu-filter: Menu Filters.
-* file-modes: File Attributes.
-* file-name-absolute-p: Relative File Names.
-* file-name-all-completions: File Name Completion.
-* file-name-as-directory: Directory Names.
-* file-name-buffer-file-type-alist: Files and MS-DOS.
-* file-name-completion: File Name Completion.
-* file-name-directory: File Name Components.
-* file-name-history: Minibuffer History.
-* file-name-nondirectory: File Name Components.
-* file-name-sans-extension: File Name Components.
-* file-name-sans-versions: File Name Components.
-* file-newer-than-file-p: Testing Accessibility.
-* file-newest-backup: Backup Names.
-* file-nlinks: File Attributes.
-* file-ownership-preserved-p: Testing Accessibility.
-* file-precious-flag: Saving Buffers.
-* file-readable-p: Testing Accessibility.
-* file-regular-p: Kinds of Files.
-* file-relative-name: File Name Expansion.
-* file-supersession: Modification Time.
-* file-symlink-p: Kinds of Files.
-* file-truename: Truenames.
-* file-writable-p: Testing Accessibility.
-* fill-column: Margins.
-* fill-individual-paragraphs: Filling.
-* fill-individual-varying-indent: Filling.
-* fill-paragraph: Filling.
-* fill-paragraph-function: Filling.
-* fill-prefix: Margins.
-* fill-region: Filling.
-* fill-region-as-paragraph: Filling.
-* fillarray: Array Functions.
-* filling a paragraph: Filling.
-* filling, automatic: Auto Filling.
-* filling, explicit: Filling.
-* filter function: Filter Functions.
-* find-backup-file-name: Backup Names.
-* find-buffer-file-type: Files and MS-DOS.
-* find-charset: Basic Charset Functions.
-* find-charset-region: MULE Characters.
-* find-charset-string: MULE Characters.
-* find-coding-system: Basic Coding System Functions.
-* find-file: Visiting Functions.
-* find-file-binary: Files and MS-DOS.
-* find-file-hooks: Visiting Functions.
-* find-file-name-handler: Magic File Names.
-* find-file-noselect: Visiting Functions.
-* find-file-not-found-hooks: Visiting Functions.
-* find-file-other-window: Visiting Functions.
-* find-file-read-only: Visiting Functions.
-* find-file-text: Files and MS-DOS.
-* find-menu-item: Modifying Menus.
-* finding files: Visiting Files.
-* finding windows: Selecting Windows.
-* first: List Elements.
-* first-change-hook: Change Hooks.
-* fixup-whitespace: User-Level Deletion.
-* float: Numeric Conversions.
-* float-output-format: Output Variables.
-* floating-point numbers, printing: Output Variables.
-* floatp: Predicates on Numbers.
-* floor: Numeric Conversions.
-* flow control characters: Flow Control.
-* flush input: Peeking and Discarding.
-* fmakunbound: Function Cells.
-* focus-frame: Input Focus.
-* following-char: Near Point.
-* font instance characteristics: Font Instance Characteristics.
-* font instance name: Font Instance Names.
-* font instance size: Font Instance Size.
-* font instance type: Font Instance Type.
-* font-instance-name: Font Instance Names.
-* font-instance-p: Font Instances.
-* font-instance-properties: Font Instance Characteristics.
-* font-instance-truename: Font Instance Names.
-* font-name: Font Convenience Functions.
-* font-properties: Font Convenience Functions.
-* font-specifier-p <1>: Font Specifiers.
-* font-specifier-p: Specifier Types.
-* font-truename: Font Convenience Functions.
-* fonts <1>: Fonts.
-* fonts: Some Terms.
-* fonts available: Font Instance Names.
-* foo: A Sample Function Description.
-* for: Argument Evaluation.
-* force-cursor-redisplay: Refresh Screen.
-* force-highlight-extent: Extents and Events.
-* forcing redisplay: Waiting.
-* format: Formatting Strings.
-* format definition: Format Conversion.
-* format of keymaps: Format of Keymaps.
-* format of menus: Menu Format.
-* format of the menubar: Menubar Format.
-* format precision: Formatting Strings.
-* format specification: Formatting Strings.
-* format-alist: Format Conversion.
-* format-buffers-menu-line: Buffers Menu.
-* format-find-file: Format Conversion.
-* format-insert-file: Format Conversion.
-* format-time-string: Time Conversion.
-* format-write-file: Format Conversion.
-* formatting strings: Formatting Strings.
-* formfeed: Character Type.
-* forms: Intro Eval.
-* forward-char: Character Motion.
-* forward-comment: Parsing Expressions.
-* forward-line: Text Lines.
-* forward-list: List Motion.
-* forward-sexp: List Motion.
-* forward-to-indentation: Motion by Indent.
-* forward-word: Word Motion.
-* fourth: List Elements.
-* frame: Frames.
-* frame configuration: Frame Configurations.
-* frame hooks: Frame Hooks.
-* frame name: Frame Name.
-* frame of terminal: Basic Windows.
-* frame position: Size and Position.
-* frame size: Size and Position.
-* frame visibility: Visibility of Frames.
-* frame-device: Basic Device Functions.
-* frame-height: Size and Position.
-* frame-icon-title-format: Frame Titles.
-* frame-iconified-p: Visibility of Frames.
-* frame-list: Finding All Frames.
-* frame-live-p: Deleting Frames.
-* frame-name: Frame Name.
-* frame-pixel-height: Size and Position.
-* frame-pixel-width: Size and Position.
-* frame-properties: Property Access.
-* frame-property: Property Access.
-* frame-root-window: Frames and Windows.
-* frame-selected-window: Frames and Windows.
-* frame-title-format: Frame Titles.
-* frame-top-window: Frames and Windows.
-* frame-totally-visible-p: Visibility of Frames.
-* frame-visible-p: Visibility of Frames.
-* frame-width: Size and Position.
-* framep: Frames.
-* free list: Garbage Collection.
-* frequency counts: Coverage Testing.
-* fround: Rounding Operations.
-* fset: Function Cells.
-* ftp-login: Cleanups.
-* ftruncate: Rounding Operations.
-* funcall: Calling Functions.
-* funcall, and debugging: Internals of Debugger.
-* function <1>: Anonymous Functions.
-* function: What Is a Function.
-* function call: Function Forms.
-* function call debugging: Function Debugging.
-* function cell: Symbol Components.
-* function cell in autoload: Autoload.
-* function definition: Function Names.
-* function descriptions: A Sample Function Description.
-* function form evaluation: Function Forms.
-* function input stream: Input Streams.
-* function invocation: Calling Functions.
-* function name: Function Names.
-* function output stream: Output Streams.
-* function quoting: Anonymous Functions.
-* function-interactive: Using Interactive.
-* function-key-map: Translating Input.
-* function-obsoleteness-doc: Obsoleteness.
-* functionals: Calling Functions.
-* functions in modes: Major Mode Conventions.
-* functions, making them interactive: Defining Commands.
-* Fundamental mode: Major Modes.
-* fundamental-mode: Auto Major Mode.
-* fundamental-mode-abbrev-table: Standard Abbrev Tables.
-* garbage collector: Garbage Collection.
-* garbage-collect: Garbage Collection.
-* gc-cons-threshold: Garbage Collection.
-* gc-message: Garbage Collection.
-* gc-pointer-glyph <1>: Garbage Collection.
-* gc-pointer-glyph: Mouse Pointer.
-* generate-new-buffer: Creating Buffers.
-* generate-new-buffer-name: Buffer Names.
-* generic-specifier-p: Specifier Types.
-* get: Object Plists.
-* get-buffer: Buffer Names.
-* get-buffer-create: Creating Buffers.
-* get-buffer-process: Process Buffers.
-* get-buffer-window: Buffers and Windows.
-* get-char-property: Examining Properties.
-* get-char-table: Working With Char Tables.
-* get-charset: Basic Charset Functions.
-* get-coding-system: Basic Coding System Functions.
-* get-database: Working With a Database.
-* get-file-buffer: Buffer File Name.
-* get-largest-window: Selecting Windows.
-* get-lru-window: Selecting Windows.
-* get-process: Process Information.
-* get-range-char-table: Working With Char Tables.
-* get-range-table: Working With Range Tables.
-* get-register: Registers.
-* get-text-property: Examining Properties.
-* get-tooltalk-message-attribute: Elisp Interface for Sending Messages.
-* getenv: System Environment.
-* getf: Other Plists.
-* gethash: Working With Hash Tables.
-* gettext: Level 3 Primitives.
-* global binding: Local Variables.
-* global break condition: Global Break Condition.
-* global keymap: Active Keymaps.
-* global mark ring: The Mark.
-* global variable: Global Variables.
-* global-abbrev-table: Standard Abbrev Tables.
-* global-key-binding: Functions for Key Lookup.
-* global-map: Active Keymaps.
-* global-mark-ring: The Mark.
-* global-mode-string: Modeline Variables.
-* global-popup-menu: Pop-Up Menus.
-* global-set-key: Key Binding Commands.
-* global-unset-key: Key Binding Commands.
-* glyph type: Glyph Type.
-* glyph-ascent: Glyph Dimensions.
-* glyph-baseline: Glyph Convenience Functions.
-* glyph-baseline-instance: Glyph Convenience Functions.
-* glyph-contrib-p: Glyph Convenience Functions.
-* glyph-contrib-p-instance: Glyph Convenience Functions.
-* glyph-descent: Glyph Dimensions.
-* glyph-face: Glyph Convenience Functions.
-* glyph-height: Glyph Dimensions.
-* glyph-image: Glyph Convenience Functions.
-* glyph-image-instance: Glyph Convenience Functions.
-* glyph-property: Glyph Properties.
-* glyph-property-instance: Glyph Properties.
-* glyph-type: Glyph Types.
-* glyph-type-list: Glyph Types.
-* glyph-width: Glyph Dimensions.
-* glyphp: Glyphs.
-* glyphs: Glyphs.
-* goto-char: Character Motion.
-* goto-line: Text Lines.
-* hack-local-variables: Auto Major Mode.
-* handling errors: Handling Errors.
-* hash notation: Printed Representation.
-* hash table: Hash Tables.
-* hash table type: Hash Table Type.
-* hash table, weak: Weak Hash Tables.
-* hash-table-count: Introduction to Hash Tables.
-* hash-table-p: Hash Tables.
-* hash-table-rehash-size: Introduction to Hash Tables.
-* hash-table-rehash-threshold: Introduction to Hash Tables.
-* hash-table-size: Introduction to Hash Tables.
-* hash-table-test: Introduction to Hash Tables.
-* hash-table-weakness: Introduction to Hash Tables.
-* hashing: Creating Symbols.
-* header comments: Library Headers.
-* help for major mode: Mode Help.
-* help-char: Help Functions.
-* help-command: Help Functions.
-* help-form: Help Functions.
-* help-map <1>: Standard Keymaps.
-* help-map: Help Functions.
-* Helper-describe-bindings: Help Functions.
-* Helper-help: Help Functions.
-* Helper-help-map: Standard Keymaps.
-* hide-annotation: Annotation Properties.
-* highlight-extent: Extents and Events.
-* history list: Minibuffer History.
-* history of commands: Command History.
-* HOME environment variable: Subprocess Creation.
-* hooks: Hooks.
-* hooks for loading: Hooks for Loading.
-* hooks for text changes: Change Hooks.
-* horizontal position: Columns.
-* horizontal scrolling: Horizontal Scrolling.
-* hscroll-glyph: Redisplay Glyphs.
-* icon-glyph-p: Glyph Types.
-* iconified frame: Visibility of Frames.
-* iconify-frame: Visibility of Frames.
-* identity: Calling Functions.
-* IEEE floating point: Float Basics.
-* if: Conditionals.
-* ignore: Calling Functions.
-* ignored-local-variables: Auto Major Mode.
-* image instance type: Image Instance Type.
-* image instance types: Image Instance Types.
-* image instances: Image Instances.
-* image instantiator conversion: Image Instantiator Conversion.
-* image specifiers: Image Specifiers.
-* image-instance-background: Image Instance Functions.
-* image-instance-depth: Image Instance Functions.
-* image-instance-file-name: Image Instance Functions.
-* image-instance-foreground: Image Instance Functions.
-* image-instance-height: Image Instance Functions.
-* image-instance-hotspot-x: Image Instance Functions.
-* image-instance-hotspot-y: Image Instance Functions.
-* image-instance-mask-file-name: Image Instance Functions.
-* image-instance-name: Image Instance Functions.
-* image-instance-p: Image Instances.
-* image-instance-string: Image Instance Functions.
-* image-instance-type: Image Instance Types.
-* image-instance-type-list: Image Instance Types.
-* image-instance-width: Image Instance Functions.
-* image-instantiator-format-list: Image Specifiers.
-* image-specifier-p <1>: Image Specifiers.
-* image-specifier-p: Specifier Types.
-* implicit progn: Sequencing.
-* inc: Simple Macro.
-* indent-according-to-mode: Mode-Specific Indent.
-* indent-code-rigidly: Region Indent.
-* indent-for-tab-command: Mode-Specific Indent.
-* indent-line-function: Mode-Specific Indent.
-* indent-region: Region Indent.
-* indent-region-function: Region Indent.
-* indent-relative: Relative Indent.
-* indent-relative-maybe: Relative Indent.
-* indent-rigidly: Region Indent.
-* indent-tabs-mode: Primitive Indent.
-* indent-to: Primitive Indent.
-* indent-to-left-margin: Margins.
-* indentation: Indentation.
-* indenting with parentheses: Parsing Expressions.
-* indirect buffers: Indirect Buffers.
-* indirect specifications: Specification List.
-* indirect variables: Variable Aliases.
-* indirect-function: Function Indirection.
-* indirect-variable: Variable Aliases.
-* indirection: Function Indirection.
-* infinite loops: Infinite Loops.
-* infinite recursion: Local Variables.
-* infinity: Float Basics.
-* Info-edit-map: Standard Keymaps.
-* Info-minibuffer-history: Minibuffer History.
-* Info-mode-map: Standard Keymaps.
-* inherit: Syntax Class Table.
-* inheriting a keymap's bindings: Inheritance and Keymaps.
-* inhibit-default-init: Init File.
-* inhibit-file-name-handlers: Magic File Names.
-* inhibit-file-name-operation: Magic File Names.
-* inhibit-quit: Quitting.
-* inhibit-read-only: Read Only Buffers.
-* inhibit-startup-echo-area-message: Start-up Summary.
-* inhibit-startup-message: Start-up Summary.
-* init file: Init File.
-* initial-frame-plist: Initial Properties.
-* initial-major-mode: Auto Major Mode.
-* initial-toolbar-spec: Other Toolbar Variables.
-* initialization: Start-up Summary.
-* inline functions: Inline Functions.
-* innermost containing parentheses: Parsing Expressions.
-* input events: Events.
-* input focus: Input Focus.
-* input modes: Input Modes.
-* input stream: Input Streams.
-* input-pending-p: Peeking and Discarding.
-* insert: Insertion.
-* insert-abbrev-table-description: Abbrev Tables.
-* insert-before-markers: Insertion.
-* insert-buffer: Commands for Insertion.
-* insert-buffer-substring: Insertion.
-* insert-char: Insertion.
-* insert-default-directory: Reading File Names.
-* insert-directory: Contents of Directories.
-* insert-directory-program: Contents of Directories.
-* insert-extent: Detached Extents.
-* insert-file-contents: Reading from Files.
-* insert-register: Registers.
-* insert-string: Insertion.
-* inserting killed text: Yank Commands.
-* insertion before point: Insertion.
-* insertion of text: Insertion.
-* inside comment: Parsing Expressions.
-* inside margin: Annotation Basics.
-* inside string: Parsing Expressions.
-* inst-list (in a specifier): Specifiers In-Depth.
-* inst-pair (in a specifier): Specifiers In-Depth.
-* installation-directory: System Environment.
-* instance (in a specifier): Specifiers In-Depth.
-* instancing (in a specifier): Specifiers In-Depth.
-* instantiator (in a specifier): Specifiers In-Depth.
-* int-char: Character Codes.
-* int-to-string: String Conversion.
-* integer to decimal: String Conversion.
-* integer to hexadecimal: Formatting Strings.
-* integer to octal: Formatting Strings.
-* integer to string: String Conversion.
-* integer-char-or-marker-p: Predicates on Markers.
-* integer-or-char-p: Predicates for Characters.
-* integer-or-marker-p: Predicates on Markers.
-* integer-specifier-p: Specifier Types.
-* integerp: Predicates on Numbers.
-* integers: Numbers.
-* interactive: Using Interactive.
-* interactive call: Interactive Call.
-* interactive code description: Interactive Codes.
-* interactive commands (Edebug): Instrumenting.
-* interactive completion: Interactive Codes.
-* interactive function: Defining Commands.
-* interactive, examples of using: Interactive Examples.
-* interactive-p: Interactive Call.
-* intern: Creating Symbols.
-* intern-soft: Creating Symbols.
-* internal-doc-file-name: Accessing Documentation.
-* interning: Creating Symbols.
-* interpreter: Evaluation.
-* interpreter-mode-alist: Auto Major Mode.
-* interprogram-cut-function: Low-Level Kill Ring.
-* interprogram-paste-function: Low-Level Kill Ring.
-* interrupt-process: Signals to Processes.
-* invalid function: Function Indirection.
-* invalid prefix key error: Changing Key Bindings.
-* invalid-function: Function Indirection.
-* invalid-read-syntax: Printed Representation.
-* invalid-regexp: Syntax of Regexps.
-* invert-face: Other Face Display Functions.
-* invisible frame: Visibility of Frames.
-* invisible text: Invisible Text.
-* invisible-text-glyph: Redisplay Glyphs.
-* invocation-directory: System Environment.
-* invocation-name: System Environment.
-* isearch-mode-map: Standard Keymaps.
-* ISO Latin 1: Case Tables.
-* ISO Latin-1 characters (input): Translating Input.
-* iso-syntax: Case Tables.
-* iso-transl: Translating Input.
-* italic: Font Instance Characteristics.
-* iteration: Iteration.
-* itimer-edit-map: Standard Keymaps.
-* joining lists: Rearrangement.
-* just-one-space: User-Level Deletion.
-* justify-current-line: Filling.
-* kept-new-versions: Numbered Backups.
-* kept-old-versions: Numbered Backups.
-* key: Keymap Terminology.
-* key binding: Keymap Terminology.
-* key lookup: Key Lookup.
-* key sequence: Key Sequence Input.
-* key sequence error: Changing Key Bindings.
-* key sequence input: Key Sequence Input.
-* key sequences: Key Sequences.
-* key translation function: Translating Input.
-* key-binding: Functions for Key Lookup.
-* key-description: Describing Characters.
-* key-press-event-p: Event Predicates.
-* key-translation-map: Translating Input.
-* keyboard macro execution: Interactive Call.
-* keyboard macro termination: Beeping.
-* keyboard macros: Keyboard Macros.
-* keyboard macros (Edebug): Edebug Execution Modes.
-* keyboard menu accelerators: Menu Accelerators.
-* keyboard-quit: Quitting.
-* keymap: Keymaps.
-* keymap entry: Key Lookup.
-* keymap format: Format of Keymaps.
-* keymap in keymap: Key Lookup.
-* keymap inheritance: Inheritance and Keymaps.
-* keymap parent: Inheritance and Keymaps.
-* keymap-default-binding: Inheritance and Keymaps.
-* keymap-fullness: Scanning Keymaps.
-* keymap-name: Creating Keymaps.
-* keymap-parents: Inheritance and Keymaps.
-* keymap-prompt: Other Keymap Functions.
-* keymapp: Format of Keymaps.
-* keymaps in modes: Major Mode Conventions.
-* keys in documentation strings: Keys in Documentation.
-* keystroke: Keymap Terminology.
-* keystroke command: What Is a Function.
-* keywordp: Specification List.
-* kill command repetition: Command Loop Info.
-* kill ring: The Kill Ring.
-* kill-all-local-variables: Creating Buffer-Local.
-* kill-append: Low-Level Kill Ring.
-* kill-buffer: Killing Buffers.
-* kill-buffer-hook: Killing Buffers.
-* kill-buffer-query-functions: Killing Buffers.
-* kill-emacs: Killing XEmacs.
-* kill-emacs-hook: Killing XEmacs.
-* kill-emacs-query-functions: Killing XEmacs.
-* kill-local-variable: Creating Buffer-Local.
-* kill-new: Low-Level Kill Ring.
-* kill-process: Signals to Processes.
-* kill-region: Kill Functions.
-* kill-ring: Internals of Kill Ring.
-* kill-ring-max: Internals of Kill Ring.
-* kill-ring-yank-pointer: Internals of Kill Ring.
-* killing buffers: Killing Buffers.
-* killing XEmacs: Killing XEmacs.
-* lambda expression: Lambda Expressions.
-* lambda expression in hook: Hooks.
-* lambda in debug: Invoking the Debugger.
-* lambda in keymap: Key Lookup.
-* lambda list: Lambda Components.
-* lambda-list (Edebug): Specification List.
-* lambda-list-keywordp: Specification List.
-* last-abbrev: Abbrev Expansion.
-* last-abbrev-location: Abbrev Expansion.
-* last-abbrev-text: Abbrev Expansion.
-* last-command: Command Loop Info.
-* last-command-char: Command Loop Info.
-* last-command-event: Command Loop Info.
-* last-input-char: Peeking and Discarding.
-* last-input-event: Peeking and Discarding.
-* last-kbd-macro: Keyboard Macros.
-* Latin-1 character set (input): Translating Input.
-* lax-plist-get: Working With Lax Plists.
-* lax-plist-member: Working With Lax Plists.
-* lax-plist-put: Working With Lax Plists.
-* lax-plist-remprop: Working With Lax Plists.
-* lax-plists-eq: Working With Lax Plists.
-* lax-plists-equal: Working With Lax Plists.
-* layout policy: Annotation Basics.
-* layout types: Annotation Basics.
-* lazy loading: Dynamic Loading.
-* LDAP: LDAP Support.
-* ldap-close: Opening and Closing a LDAP Connection.
-* ldap-default-base: LDAP Variables.
-* ldap-default-host: LDAP Variables.
-* ldap-default-port: LDAP Variables.
-* ldap-host: The LDAP Lisp Object.
-* ldap-host-parameters-alist: LDAP Variables.
-* ldap-live-p: The LDAP Lisp Object.
-* ldap-open: Opening and Closing a LDAP Connection.
-* ldap-search: The High-Level LDAP API.
-* ldap-search-internal: Searching on a LDAP Server (Low-level).
-* ldapp: The LDAP Lisp Object.
-* left-margin: Margins.
-* left-margin-width: Margin Primitives.
-* left-toolbar: Specifying the Toolbar.
-* left-toolbar-visible-p: Other Toolbar Variables.
-* left-toolbar-width: Other Toolbar Variables.
-* length: Sequence Functions.
-* let: Local Variables.
-* let*: Local Variables.
-* let-specifier: Adding Specifications.
-* lexical binding (Edebug): Edebug Eval.
-* lexical comparison: Text Comparison.
-* library: Loading.
-* library compilation: Compilation Functions.
-* library header comments: Library Headers.
-* line wrapping: Truncation.
-* lines: Text Lines.
-* lines in region: Text Lines.
-* linking files: Changing File Attributes.
-* Lisp debugger: Debugger.
-* Lisp expression motion: List Motion.
-* Lisp history: Lisp History.
-* Lisp library: Loading.
-* Lisp nesting error: Eval.
-* Lisp object: Lisp Data Types.
-* Lisp printer: Output Functions.
-* Lisp reader: Streams Intro.
-* lisp-interaction-mode-map: Standard Keymaps.
-* lisp-mode-abbrev-table: Standard Abbrev Tables.
-* lisp-mode-map: Standard Keymaps.
-* lisp-mode.el: Example Major Modes.
-* list <1>: Building Lists.
-* list: Lists.
-* list elements: List Elements.
-* list form evaluation: Classifying Lists.
-* list in keymap: Key Lookup.
-* list length: Sequence Functions.
-* list motion: List Motion.
-* list structure: Cons Cells.
-* list-buffers: The Buffer List.
-* list-buffers-directory: Buffer File Name.
-* list-fonts: Font Instance Names.
-* list-processes: Process Information.
-* listp: List-related Predicates.
-* lists and cons cells: Cons Cells.
-* lists as sets: Sets And Lists.
-* lists represented as boxes: Lists as Boxes.
-* literal evaluation: Self-Evaluating Forms.
-* lmessage: The Echo Area.
-* ln: Changing File Attributes.
-* load: How Programs Do Loading.
-* load error with require: Named Features.
-* load errors: How Programs Do Loading.
-* load-average: System Environment.
-* load-default-sounds: Beeping.
-* load-history: Unloading.
-* load-ignore-elc-files: How Programs Do Loading.
-* load-in-progress: How Programs Do Loading.
-* load-path: How Programs Do Loading.
-* load-read-function: How Programs Do Loading.
-* load-sound-file: Beeping.
-* load-warn-when-source-newer: How Programs Do Loading.
-* load-warn-when-source-only: How Programs Do Loading.
-* loading: Loading.
-* loading hooks: Hooks for Loading.
-* loadup.el: Building XEmacs.
-* local binding: Local Variables.
-* local keymap: Active Keymaps.
-* local variables: Local Variables.
-* local-abbrev-table: Standard Abbrev Tables.
-* local-key-binding: Functions for Key Lookup.
-* local-set-key: Key Binding Commands.
-* local-unset-key: Key Binding Commands.
-* local-variable-p: Creating Buffer-Local.
-* local-write-file-hooks: Saving Buffers.
-* locale (in a specifier): Specifiers In-Depth.
-* locate-file: How Programs Do Loading.
-* locate-file-clear-hashing: How Programs Do Loading.
-* lock-buffer: File Locks.
-* log: Math Functions.
-* log-message-ignore-labels: The Echo Area.
-* log-message-ignore-regexps: The Echo Area.
-* log-message-max-size: The Echo Area.
-* log-warning-minimum-level: Warnings.
-* log-warning-suppressed-classes: Warnings.
-* log10: Math Functions.
-* logand: Bitwise Operations.
-* logb: Float Basics.
-* logical and: Bitwise Operations.
-* logical exclusive or: Bitwise Operations.
-* logical inclusive or: Bitwise Operations.
-* logical not: Bitwise Operations.
-* logical shift: Bitwise Operations.
-* logior: Bitwise Operations.
-* lognot: Bitwise Operations.
-* logxor: Bitwise Operations.
-* looking-at: Regexp Search.
-* lookup-key: Functions for Key Lookup.
-* loops, infinite: Infinite Loops.
-* lower case: Character Case.
-* lower-frame: Raising and Lowering.
-* lowering a frame: Raising and Lowering.
-* lsh: Bitwise Operations.
-* lwarn: Warnings.
-* M-x: Interactive Call.
-* Maclisp: Lisp History.
-* macro: What Is a Function.
-* macro argument evaluation: Argument Evaluation.
-* macro call: Expansion.
-* macro call evaluation: Macro Forms.
-* macro compilation: Compilation Functions.
-* macro descriptions: A Sample Function Description.
-* macro expansion: Expansion.
-* macroexpand: Expansion.
-* macros: Macros.
-* magic file names: Magic File Names.
-* mail-host-address: System Environment.
-* major mode: Major Modes.
-* major mode hook: Major Mode Conventions.
-* major mode keymap: Active Keymaps.
-* major-mode: Mode Help.
-* make-abbrev-table: Abbrev Tables.
-* make-annotation: Annotation Primitives.
-* make-auto-save-file-name: Auto-Saving.
-* make-backup-file-name: Backup Names.
-* make-backup-files: Making Backups.
-* make-bit-vector: Bit Vector Functions.
-* make-byte-code: Compiled-Function Objects.
-* make-char: MULE Characters.
-* make-char-table: Working With Char Tables.
-* make-charset: Basic Charset Functions.
-* make-coding-system: Basic Coding System Functions.
-* make-composite-char: Composite Characters.
-* make-device: Connecting to a Console or Device.
-* make-directory: Create/Delete Dirs.
-* make-display-table: Display Table Format.
-* make-event: Working With Events.
-* make-extent: Creating and Modifying Extents.
-* make-face: Basic Face Functions.
-* make-file-part: Creating a Partial File.
-* make-font-instance: Font Instances.
-* make-frame: Creating Frames.
-* make-frame-invisible: Visibility of Frames.
-* make-frame-visible: Visibility of Frames.
-* make-glyph: Creating Glyphs.
-* make-glyph-internal: Creating Glyphs.
-* make-hash-table: Introduction to Hash Tables.
-* make-icon-glyph: Creating Glyphs.
-* make-image-instance: Image Instance Functions.
-* make-image-specifier: Image Specifiers.
-* make-indirect-buffer: Indirect Buffers.
-* make-keymap: Creating Keymaps.
-* make-list: Building Lists.
-* make-local-hook: Hooks.
-* make-local-variable: Creating Buffer-Local.
-* make-marker: Creating Markers.
-* make-obsolete: Obsoleteness.
-* make-obsolete-variable: Obsoleteness.
-* make-pointer-glyph: Creating Glyphs.
-* make-range-table: Introduction to Range Tables.
-* make-reverse-direction-charset: Basic Charset Functions.
-* make-sparse-keymap: Creating Keymaps.
-* make-specifier: Creating Specifiers.
-* make-specifier-and-init: Creating Specifiers.
-* make-string: Creating Strings.
-* make-symbol: Creating Symbols.
-* make-symbolic-link: Changing File Attributes.
-* make-syntax-table: Syntax Table Functions.
-* make-temp-name: Unique File Names.
-* make-tooltalk-message: Elisp Interface for Sending Messages.
-* make-tooltalk-pattern: Elisp Interface for Receiving Messages.
-* make-tty-device: Connecting to a Console or Device.
-* make-variable-buffer-local: Creating Buffer-Local.
-* make-vector: Vector Functions.
-* make-weak-list: Weak Lists.
-* make-x-device: Connecting to a Console or Device.
-* makunbound: Void Variables.
-* Manual-page-minibuffer-history: Minibuffer History.
-* map-char-table: Working With Char Tables.
-* map-database: Working With a Database.
-* map-extent-children: Mapping Over Extents.
-* map-extents: Mapping Over Extents.
-* map-frame-hook: Frame Hooks.
-* map-keymap: Scanning Keymaps.
-* map-range-table: Working With Range Tables.
-* map-specifier: Other Specification Functions.
-* map-y-or-n-p: Multiple Queries.
-* mapatoms: Creating Symbols.
-* mapcar: Mapping Functions.
-* mapcar-extents: Mapping Over Extents.
-* mapconcat: Mapping Functions.
-* maphash: Working With Hash Tables.
-* mapping functions: Mapping Functions.
-* margin: Annotation Basics.
-* margin width: Margin Primitives.
-* mark: The Mark.
-* mark excursion: Excursions.
-* mark ring: The Mark.
-* mark, the: The Mark.
-* mark-marker: The Mark.
-* mark-ring: The Mark.
-* mark-ring-max: The Mark.
-* marker argument: Interactive Codes.
-* marker garbage collection: Overview of Markers.
-* marker input stream: Input Streams.
-* marker output stream: Output Streams.
-* marker relocation: Overview of Markers.
-* marker-buffer: Information from Markers.
-* marker-position: Information from Markers.
-* markerp: Predicates on Markers.
-* markers: Markers.
-* markers as numbers: Overview of Markers.
-* markers vs. extents: Overview of Markers.
-* match data: Match Data.
-* match-beginning: Simple Match Data.
-* match-data: Entire Match Data.
-* match-end: Simple Match Data.
-* match-string: Simple Match Data.
-* mathematical functions: Math Functions.
-* max: Comparison of Numbers.
-* max-lisp-eval-depth: Eval.
-* max-specpdl-size: Local Variables.
-* md5: Transformations.
-* MD5 digests: Transformations.
-* member: Sets And Lists.
-* membership in a list: Sets And Lists.
-* memory allocation: Garbage Collection.
-* memory-limit: Garbage Collection.
-* memq: Sets And Lists.
-* menu: Menus.
-* menu accelerators: Menu Accelerators.
-* menu filters: Menu Filters.
-* menu format: Menu Format.
-* menu-accelerator-enabled: Menu Accelerator Functions.
-* menu-accelerator-map: Menu Accelerator Functions.
-* menu-accelerator-modifiers: Menu Accelerator Functions.
-* menu-accelerator-prefix: Menu Accelerator Functions.
-* menu-no-selection-hook: Menubar.
-* menubar: Menubar.
-* menubar format: Menubar Format.
-* menubar-configuration: Menu Format.
-* menubar-pointer-glyph: Mouse Pointer.
-* menubar-show-keybindings: Menubar.
-* message: The Echo Area.
-* meta character printing: Describing Characters.
-* meta-prefix-char: Functions for Key Lookup.
-* min: Comparison of Numbers.
-* minibuffer: Minibuffers.
-* minibuffer history: Minibuffer History.
-* minibuffer input: Recursive Editing.
-* minibuffer window: Cyclic Window Ordering.
-* minibuffer-complete: Completion Commands.
-* minibuffer-complete-and-exit: Completion Commands.
-* minibuffer-complete-word: Completion Commands.
-* minibuffer-completion-confirm: Completion Commands.
-* minibuffer-completion-help: Completion Commands.
-* minibuffer-completion-predicate: Completion Commands.
-* minibuffer-completion-table: Completion Commands.
-* minibuffer-depth: Minibuffer Misc.
-* minibuffer-exit-hook: Minibuffer Misc.
-* minibuffer-frame-plist: Initial Properties.
-* minibuffer-help-form: Minibuffer Misc.
-* minibuffer-history: Minibuffer History.
-* minibuffer-local-completion-map <1>: Standard Keymaps.
-* minibuffer-local-completion-map: Completion Commands.
-* minibuffer-local-isearch-map: Standard Keymaps.
-* minibuffer-local-map <1>: Standard Keymaps.
-* minibuffer-local-map: Text from Minibuffer.
-* minibuffer-local-must-match-map <1>: Standard Keymaps.
-* minibuffer-local-must-match-map: Completion Commands.
-* minibuffer-prompt: Minibuffer Misc.
-* minibuffer-prompt-width: Minibuffer Misc.
-* minibuffer-scroll-window: Minibuffer Misc.
-* minibuffer-setup-hook: Minibuffer Misc.
-* minibuffer-window: Minibuffer Misc.
-* minibuffer-window-active-p: Minibuffer Misc.
-* minimum window size: Resizing Windows.
-* minor mode: Minor Modes.
-* minor mode conventions: Minor Mode Conventions.
-* minor-mode-alist: Modeline Variables.
-* minor-mode-key-binding: Functions for Key Lookup.
-* minor-mode-map-alist: Active Keymaps.
-* misc-user-event-p: Event Predicates.
-* mod: Arithmetic Operations.
-* mode: Modes.
-* mode help: Mode Help.
-* mode hook: Major Mode Conventions.
-* mode loading: Major Mode Conventions.
-* mode variable: Minor Mode Conventions.
-* mode-class property: Major Mode Conventions.
-* mode-name: Modeline Variables.
-* mode-popup-menu: Pop-Up Menus.
-* mode-specific-map <1>: Standard Keymaps.
-* mode-specific-map: Prefix Keys.
-* modeline: Modeline Format.
-* modeline construct: Modeline Data.
-* modeline-buffer-identification: Modeline Variables.
-* modeline-format: Modeline Data.
-* modeline-map <1>: Standard Keymaps.
-* modeline-map: Active Keymaps.
-* modeline-modified: Modeline Variables.
-* modeline-pointer-glyph: Mouse Pointer.
-* modeline-process: Modeline Variables.
-* modification flag (of buffer): Buffer Modification.
-* modification of lists: Rearrangement.
-* modification time, comparison of: Modification Time.
-* modify-syntax-entry: Syntax Table Functions.
-* modulus: Arithmetic Operations.
-* momentary-string-display: Temporary Displays.
-* mono-pixmap-image-instance-p: Image Instance Types.
-* motion-event-p: Event Predicates.
-* mouse cursor: Mouse Pointer.
-* mouse pointer: Mouse Pointer.
-* mouse-event-p: Event Predicates.
-* mouse-grabbed-buffer: Active Keymaps.
-* mouse-highlight-priority: Extents and Events.
-* move-marker: Changing Markers.
-* move-to-column: Columns.
-* move-to-left-margin: Margins.
-* move-to-window-line: Screen Lines.
-* MS-DOS and file modes: Changing File Attributes.
-* MS-DOS file types: Files and MS-DOS.
-* MSWindows OLE: MSWindows OLE.
-* multilingual string formatting: Formatting Strings.
-* multiple windows: Basic Windows.
-* named function: Function Names.
-* NaN: Float Basics.
-* narrow-to-page: Narrowing.
-* narrow-to-region: Narrowing.
-* narrowing: Narrowing.
-* natnum-specifier-p: Specifier Types.
-* natnump: Predicates on Numbers.
-* natural numbers: Predicates on Numbers.
-* nconc: Rearrangement.
-* negative infinity: Float Basics.
-* negative-argument: Prefix Command Arguments.
-* network connection: Network.
-* new file message: Subroutines of Visiting.
-* newline <1>: Commands for Insertion.
-* newline: Character Type.
-* newline and Auto Fill mode: Commands for Insertion.
-* newline in print: Output Functions.
-* newline in strings: String Type.
-* newline-and-indent: Mode-Specific Indent.
-* next input: Peeking and Discarding.
-* next-command-event: Reading One Event.
-* next-event: Reading One Event.
-* next-extent: Finding Extents.
-* next-frame: Finding All Frames.
-* next-history-element: Minibuffer Misc.
-* next-matching-history-element: Minibuffer Misc.
-* next-property-change: Property Search.
-* next-screen-context-lines: Vertical Scrolling.
-* next-single-property-change: Property Search.
-* next-window: Cyclic Window Ordering.
-* nil: Constant Variables.
-* nil and lists: Cons Cells.
-* nil in keymap: Key Lookup.
-* nil in lists: Cons Cell Type.
-* nil input stream: Input Streams.
-* nil output stream: Output Streams.
-* nil, uses of: nil and t.
-* ninth: List Elements.
-* nlistp: List-related Predicates.
-* no-catch: Catch and Throw.
-* no-redraw-on-reenter: Refresh Screen.
-* nondirectory part (of file name): File Name Components.
-* noninteractive: Batch Mode.
-* noninteractive use: Batch Mode.
-* nonlocal exits: Nonlocal Exits.
-* nonprinting characters, reading: Quoted Character Input.
-* nontext-pointer-glyph: Mouse Pointer.
-* normal-mode: Auto Major Mode.
-* not: Combining Conditions.
-* not-modified: Buffer Modification.
-* nothing-image-instance-p: Image Instance Types.
-* nreverse: Rearrangement.
-* nth: List Elements.
-* nthcdr: List Elements.
-* null: List-related Predicates.
-* number equality: Comparison of Numbers.
-* number-char-or-marker-p: Predicates on Markers.
-* number-or-marker-p: Predicates on Markers.
-* number-to-string: String Conversion.
-* numberp: Predicates on Numbers.
-* numbers: Numbers.
-* numeric prefix: Formatting Strings.
-* numeric prefix argument: Prefix Command Arguments.
-* numeric prefix argument usage: Interactive Codes.
-* obarray: Creating Symbols.
-* obarray in completion: Basic Completion.
-* objc-mode-map: Standard Keymaps.
-* object: Lisp Data Types.
-* object to string: Output Functions.
-* object-plist: Object Plists.
-* oblique: Font Instance Characteristics.
-* obsolete buffer: Modification Time.
-* occur-mode-map: Standard Keymaps.
-* octal character code: Character Type.
-* octal character input: Quoted Character Input.
-* octal-escape-glyph: Redisplay Glyphs.
-* OffiX DND: OffiX DND.
-* old-eq: Equality Predicates.
-* one-window-p: Splitting Windows.
-* only-global-abbrevs: Defining Abbrevs.
-* open-database: Connecting to a Database.
-* open-dribble-file: Recording Input.
-* open-network-stream: Network.
-* open-termscript: Terminal Output.
-* open parenthesis character: Syntax Class Table.
-* operating system environment: System Environment.
-* option descriptions: A Sample Variable Description.
-* optional arguments: Argument List.
-* options on command line: Command Line Arguments.
-* or: Combining Conditions.
-* order of extents: Extent Endpoints.
-* ordering of windows, cyclic: Cyclic Window Ordering.
-* other-buffer: The Buffer List.
-* other-window: Cyclic Window Ordering.
-* other-window-scroll-buffer: Vertical Scrolling.
-* Outline mode: Substitution.
-* output from processes: Output from Processes.
-* output stream: Output Streams.
-* outside margin: Annotation Basics.
-* overflow: Integer Basics.
-* overlay arrow: Overlay Arrow.
-* overlay-arrow-position: Overlay Arrow.
-* overlay-arrow-string: Overlay Arrow.
-* overriding-local-map <1>: Standard Keymaps.
-* overriding-local-map: Active Keymaps.
-* overriding-terminal-local-map: Active Keymaps.
-* overwrite-mode: Commands for Insertion.
-* padding: Formatting Strings.
-* page-delimiter: Standard Regexps.
-* paired delimiter: Syntax Class Table.
-* paragraph-separate: Standard Regexps.
-* paragraph-start: Standard Regexps.
-* parent of a keymap: Inheritance and Keymaps.
-* parent process: Processes.
-* parent, of extent: Extent Parents.
-* parenthesis: Cons Cell Type.
-* parenthesis depth: Parsing Expressions.
-* parenthesis matching: Blinking.
-* parenthesis syntax: Syntax Class Table.
-* parse state: Parsing Expressions.
-* parse-partial-sexp: Parsing Expressions.
-* parse-sexp-ignore-comments: Parsing Expressions.
-* parsing: Syntax Tables.
-* partial files: Partial Files.
-* passwd-echo: Reading a Password.
-* passwd-invert-frame-when-keyboard-grabbed: Reading a Password.
-* passwords, reading: Reading a Password.
-* PATH environment variable: Subprocess Creation.
-* path-separator: System Environment.
-* pausing: Waiting.
-* peeking at input: Peeking and Discarding.
-* percent symbol in modeline: Modeline Data.
-* perform-replace: Search and Replace.
-* performance analysis: Coverage Testing.
-* permanent local variable: Creating Buffer-Local.
-* permission: File Attributes.
-* pipes: Asynchronous Processes.
-* play-sound: Beeping.
-* play-sound-file: Beeping.
-* plist: Property Lists.
-* plist, symbol: Symbol Properties.
-* plist-get: Working With Normal Plists.
-* plist-member: Working With Normal Plists.
-* plist-put: Working With Normal Plists.
-* plist-remprop: Working With Normal Plists.
-* plist-to-alist: Converting Plists To/From Alists.
-* plists-eq <1>: Other Plists.
-* plists-eq: Working With Normal Plists.
-* plists-equal <1>: Other Plists.
-* plists-equal: Working With Normal Plists.
-* point: Point.
-* point excursion: Excursions.
-* point in window: Window Point.
-* point with narrowing: Point.
-* point-marker: Creating Markers.
-* point-max: Point.
-* point-max-marker: Creating Markers.
-* point-min: Point.
-* point-min-marker: Creating Markers.
-* pointer (mouse): Mouse Pointer.
-* pointer-glyph-p: Glyph Types.
-* pointer-image-instance-p: Image Instance Types.
-* pop-global-mark: The Mark.
-* pop-mark: The Mark.
-* pop-to-buffer: Displaying Buffers.
-* pop-up menu: Pop-Up Menus.
-* pop-up-frame-function: Choosing Window.
-* pop-up-frame-plist: Choosing Window.
-* pop-up-frames: Choosing Window.
-* pop-up-windows: Choosing Window.
-* popup-buffer-menu: Pop-Up Menus.
-* popup-dialog-box: Dialog Box Functions.
-* popup-menu: Pop-Up Menus.
-* popup-menu-titles: Pop-Up Menus.
-* popup-menu-up-p: Pop-Up Menus.
-* popup-menubar-menu: Pop-Up Menus.
-* popup-mode-menu: Pop-Up Menus.
-* pos-visible-in-window-p: Window Start.
-* position (in buffer): Positions.
-* position argument: Interactive Codes.
-* position in window: Window Point.
-* position of frame: Size and Position.
-* position of window: Position of Window.
-* positive infinity: Float Basics.
-* posix-looking-at: POSIX Regexps.
-* posix-search-backward: POSIX Regexps.
-* posix-search-forward: POSIX Regexps.
-* posix-string-match: POSIX Regexps.
-* post-command-hook: Command Overview.
-* post-gc-hook: Garbage Collection.
-* pre-abbrev-expand-hook: Abbrev Expansion.
-* pre-command-hook: Command Overview.
-* pre-gc-hook: Garbage Collection.
-* preceding-char: Near Point.
-* precision of formatted numbers: Formatting Strings.
-* predicates: Type Predicates.
-* prefix argument: Prefix Command Arguments.
-* prefix argument unreading: Peeking and Discarding.
-* prefix command: Prefix Keys.
-* prefix key: Prefix Keys.
-* prefix-arg: Prefix Command Arguments.
-* prefix-help-command: Help Functions.
-* prefix-numeric-value: Prefix Command Arguments.
-* preventing backtracking: Specification List.
-* preventing prefix key: Key Lookup.
-* previous complete subexpression: Parsing Expressions.
-* previous-extent: Finding Extents.
-* previous-frame: Finding All Frames.
-* previous-history-element: Minibuffer Misc.
-* previous-matching-history-element: Minibuffer Misc.
-* previous-property-change: Property Search.
-* previous-single-property-change: Property Search.
-* previous-window: Cyclic Window Ordering.
-* primitive: What Is a Function.
-* primitive type: Lisp Data Types.
-* primitive types: Primitive Types.
-* primitive-undo: Undo.
-* prin1: Output Functions.
-* prin1-to-string: Output Functions.
-* princ: Output Functions.
-* print: Output Functions.
-* print example: Output Streams.
-* print name cell: Symbol Components.
-* print-escape-newlines: Output Variables.
-* print-gensym: Output Variables.
-* print-help-return-message: Help Functions.
-* print-length: Output Variables.
-* print-level: Output Variables.
-* print-readably <1>: Output Variables.
-* print-readably: Printing in Edebug.
-* print-string-length: Output Variables.
-* printed representation: Printed Representation.
-* printed representation for characters: Character Type.
-* printing: Streams Intro.
-* printing (Edebug): Printing in Edebug.
-* printing circular structures: Printing in Edebug.
-* printing floating-point numbers: Output Variables.
-* printing limits: Output Variables.
-* printing notation: Printing Notation.
-* printing readably: Output Variables.
-* printing uninterned symbols: Output Variables.
-* priority of an extent: Intro to Extents.
-* process: Processes.
-* process filter: Filter Functions.
-* process input: Input to Processes.
-* process output: Output from Processes.
-* process sentinel: Sentinels.
-* process signals: Signals to Processes.
-* process window size: Process Window Size.
-* process-buffer: Process Buffers.
-* process-command: Process Information.
-* process-connection-type: Asynchronous Processes.
-* process-environment: System Environment.
-* process-event-p: Event Predicates.
-* process-exit-status: Process Information.
-* process-filter: Filter Functions.
-* process-id: Process Information.
-* process-kill-without-query: Deleting Processes.
-* process-kill-without-query-p: Process Information.
-* process-list: Process Information.
-* process-mark: Process Buffers.
-* process-name: Process Information.
-* process-send-eof: Input to Processes.
-* process-send-region: Input to Processes.
-* process-send-string: Input to Processes.
-* process-sentinel: Sentinels.
-* process-status: Process Information.
-* process-tty-name: Process Information.
-* processp: Processes.
-* profile.el: Compilation Tips.
-* profiling: Compilation Tips.
-* prog1: Sequencing.
-* prog2: Sequencing.
-* progn: Sequencing.
-* program arguments: Subprocess Creation.
-* program directories: Subprocess Creation.
-* programmed completion: Programmed Completion.
-* programming types: Programming Types.
-* properties of strings: String Properties.
-* properties of text: Text Properties.
-* property list: Property Lists.
-* property list cell (symbol): Symbol Components.
-* property list, symbol: Symbol Properties.
-* property lists vs association lists: Plists and Alists.
-* property of an extent: Extent Properties.
-* protected forms: Cleanups.
-* provide: Named Features.
-* providing features: Named Features.
-* PTYs: Asynchronous Processes.
-* punctuation character: Syntax Class Table.
-* pure storage: Pure Storage.
-* pure-bytes-used: Pure Storage.
-* purecopy: Pure Storage.
-* purify-flag: Pure Storage.
-* push-mark: The Mark.
-* put: Object Plists.
-* put-char-table: Working With Char Tables.
-* put-database: Working With a Database.
-* put-range-table: Working With Range Tables.
-* put-text-property: Changing Properties.
-* putf: Other Plists.
-* puthash: Working With Hash Tables.
-* query-replace-history: Minibuffer History.
-* query-replace-map <1>: Standard Keymaps.
-* query-replace-map: Search and Replace.
-* querying the user: Yes-or-No Queries.
-* question mark in character constant: Character Type.
-* quietly-read-abbrev-file: Abbrev Files.
-* quit-flag: Quitting.
-* quit-process: Signals to Processes.
-* quitting: Quitting.
-* quitting from infinite loop: Infinite Loops.
-* quote: Quoting.
-* quote character: Parsing Expressions.
-* quoted character input: Quoted Character Input.
-* quoted-insert suppression: Changing Key Bindings.
-* quoting: Quoting.
-* quoting characters in printing: Output Functions.
-* quoting using apostrophe: Quoting.
-* raise-frame: Raising and Lowering.
-* raising a frame: Raising and Lowering.
-* random: Random Numbers.
-* random numbers: Random Numbers.
-* range table type: Range Table Type.
-* Range Tables: Range Tables.
-* range-table-p: Range Tables.
-* rassoc: Association Lists.
-* rassq: Association Lists.
-* raw prefix argument: Prefix Command Arguments.
-* raw prefix argument usage: Interactive Codes.
-* re-search-backward: Regexp Search.
-* re-search-forward: Regexp Search.
-* read: Input Functions.
-* read command name: Interactive Call.
-* read syntax: Printed Representation.
-* read syntax for characters: Character Type.
-* read-buffer: High-Level Completion.
-* read-char: Reading One Event.
-* read-command: High-Level Completion.
-* read-expression-history: Minibuffer History.
-* read-expression-map: Standard Keymaps.
-* read-file-name: Reading File Names.
-* read-from-minibuffer: Text from Minibuffer.
-* read-from-string: Input Functions.
-* read-key-sequence: Key Sequence Input.
-* read-minibuffer: Object from Minibuffer.
-* read-only buffer: Read Only Buffers.
-* read-only buffers in interactive: Using Interactive.
-* read-passwd: Reading a Password.
-* read-quoted-char: Quoted Character Input.
-* read-quoted-char quitting: Quitting.
-* read-shell-command-map: Standard Keymaps.
-* read-string: Text from Minibuffer.
-* read-variable: High-Level Completion.
-* reading: Streams Intro.
-* reading (Edebug): Reading in Edebug.
-* reading interactive arguments: Interactive Codes.
-* reading symbols: Creating Symbols.
-* rearrangement of lists: Rearrangement.
-* rebinding: Changing Key Bindings.
-* receiving ToolTalk messages: Receiving Messages.
-* recent-auto-save-p: Auto-Saving.
-* recent-keys: Recording Input.
-* recent-keys-ring-size: Recording Input.
-* recenter: Vertical Scrolling.
-* record command history: Interactive Call.
-* recursion: Iteration.
-* recursion-depth: Recursive Editing.
-* recursive command loop: Recursive Editing.
-* recursive editing level: Recursive Editing.
-* recursive evaluation: Intro Eval.
-* recursive-edit: Recursive Editing.
-* redo: Undo.
-* redraw-display: Refresh Screen.
-* redraw-frame: Refresh Screen.
-* redraw-modeline: Modeline Format.
-* refresh display: Refresh Screen.
-* regexp: Regular Expressions.
-* regexp alternative: Syntax of Regexps.
-* regexp grouping: Syntax of Regexps.
-* regexp searching: Regexp Search.
-* regexp-history: Minibuffer History.
-* regexp-quote: Syntax of Regexps.
-* regexps used standardly in editing: Standard Regexps.
-* region argument: Interactive Codes.
-* region, the: The Region.
-* region-active-p: The Region.
-* region-beginning: The Region.
-* region-end: The Region.
-* region-exists-p: The Region.
-* register-alist: Registers.
-* register-ccl-program: Calling CCL.
-* register-tooltalk-pattern: Elisp Interface for Receiving Messages.
-* registers: Registers.
-* regular expression: Regular Expressions.
-* regular expression searching: Regexp Search.
-* reindent-then-newline-and-indent: Mode-Specific Indent.
-* relabel-menu-item: Modifying Menus.
-* relative file name: Relative File Names.
-* remainder: Arithmetic Operations.
-* remassoc: Association Lists.
-* remassq: Association Lists.
-* remhash: Working With Hash Tables.
-* remove-database: Working With a Database.
-* remove-face-property: Face Properties.
-* remove-glyph-property: Glyph Properties.
-* remove-hook: Hooks.
-* remove-range-table: Working With Range Tables.
-* remove-specifier: Other Specification Functions.
-* remove-text-properties: Changing Properties.
-* remprop: Object Plists.
-* remrassoc: Association Lists.
-* remrassq: Association Lists.
-* rename-auto-save-file: Auto-Saving.
-* rename-buffer: Buffer Names.
-* rename-file: Changing File Attributes.
-* renaming files: Changing File Attributes.
-* repeated loading: Repeated Loading.
-* replace bindings: Changing Key Bindings.
-* replace characters: Substitution.
-* replace-buffer-in-windows: Displaying Buffers.
-* replace-match: Replacing Match.
-* replacement: Search and Replace.
-* repositioning format arguments: Formatting Strings.
-* require: Named Features.
-* require-final-newline: Saving Buffers.
-* requiring features: Named Features.
-* reset-char-table: Working With Char Tables.
-* resize redisplay: Size and Position.
-* rest arguments: Argument List.
-* restriction (in a buffer): Narrowing.
-* resume (cf. no-redraw-on-reenter): Refresh Screen.
-* return: Character Type.
-* return-tooltalk-message: Elisp Interface for Sending Messages.
-* reveal-annotation: Annotation Properties.
-* reverse: Building Lists.
-* reversing a list: Rearrangement.
-* revert-buffer: Reverting.
-* revert-buffer-function: Reverting.
-* revert-buffer-insert-file-contents-function: Reverting.
-* right-margin-width: Margin Primitives.
-* right-toolbar: Specifying the Toolbar.
-* right-toolbar-visible-p: Other Toolbar Variables.
-* right-toolbar-width: Other Toolbar Variables.
-* rm: Changing File Attributes.
-* round: Numeric Conversions.
-* rounding in conversions: Numeric Conversions.
-* rounding without conversion: Rounding Operations.
-* rplaca: Modifying Lists.
-* rplacd: Modifying Lists.
-* run time stack: Internals of Debugger.
-* run-emacs-from-temacs: Building XEmacs.
-* run-hooks: Hooks.
-* runnable temacs: Building XEmacs.
-* same-window-buffer-names: Choosing Window.
-* same-window-regexps: Choosing Window.
-* save-abbrevs: Abbrev Files.
-* save-buffer: Saving Buffers.
-* save-current-buffer: Excursions.
-* save-excursion: Excursions.
-* save-excursion (Edebug): Edebug Display Update.
-* save-match-data: Saving Match Data.
-* save-restriction: Narrowing.
-* save-selected-frame: Input Focus.
-* save-selected-window <1>: Excursions.
-* save-selected-window: Selecting Windows.
-* save-some-buffers: Saving Buffers.
-* save-window-excursion: Window Configurations.
-* saving text properties: Saving Properties.
-* saving window information: Window Configurations.
-* scan-lists: Parsing Expressions.
-* scan-sexps: Parsing Expressions.
-* scope: Variable Scoping.
-* screen layout: Window Configuration Type.
-* scroll-conservatively: Vertical Scrolling.
-* scroll-down: Vertical Scrolling.
-* scroll-left: Horizontal Scrolling.
-* scroll-other-window: Vertical Scrolling.
-* scroll-right: Horizontal Scrolling.
-* scroll-step: Vertical Scrolling.
-* scroll-up: Vertical Scrolling.
-* scrollbar-pointer-glyph: Mouse Pointer.
-* scrollbars: Scrollbars.
-* scrolling vertically: Vertical Scrolling.
-* search-backward: String Search.
-* search-failed: String Search.
-* search-forward: String Search.
-* searching: Searching and Matching.
-* searching and case: Searching and Case.
-* searching for regexp: Regexp Search.
-* second: List Elements.
-* select-console: The Selected Console and Device.
-* select-device: The Selected Console and Device.
-* select-frame: Input Focus.
-* select-frame-hook: Frame Hooks.
-* select-window: Selecting Windows.
-* selected frame: Input Focus.
-* selected window: Basic Windows.
-* selected-console: The Selected Console and Device.
-* selected-device: The Selected Console and Device.
-* selected-frame: Input Focus.
-* selected-window: Selecting Windows.
-* selecting a buffer: Current Buffer.
-* selecting windows: Selecting Windows.
-* selection (for X windows): X Selections.
-* selection-pointer-glyph: Mouse Pointer.
-* selective display: Selective Display.
-* selective-display: Selective Display.
-* selective-display-ellipses: Selective Display.
-* self-evaluating form: Self-Evaluating Forms.
-* self-insert-and-exit: Minibuffer Misc.
-* self-insert-command: Commands for Insertion.
-* self-insert-command override: Changing Key Bindings.
-* self-insert-command, minor modes: Keymaps and Minor Modes.
-* self-insertion: Commands for Insertion.
-* send-string-to-terminal: Terminal Output.
-* send-tooltalk-message: Elisp Interface for Sending Messages.
-* sending signals: Signals to Processes.
-* sending ToolTalk messages: Sending Messages.
-* sentence-end: Standard Regexps.
-* sentinel: Sentinels.
-* sequence: Sequences Arrays Vectors.
-* sequence length: Sequence Functions.
-* sequencep: Sequence Functions.
-* set: Setting Variables.
-* set-annotation-action: Annotation Properties.
-* set-annotation-data: Annotation Properties.
-* set-annotation-down-glyph: Annotation Properties.
-* set-annotation-face: Annotation Properties.
-* set-annotation-glyph: Annotation Properties.
-* set-annotation-layout: Annotation Properties.
-* set-annotation-menu: Annotation Properties.
-* set-auto-mode: Auto Major Mode.
-* set-buffer: Current Buffer.
-* set-buffer-auto-saved: Auto-Saving.
-* set-buffer-major-mode: Auto Major Mode.
-* set-buffer-menubar: Menubar.
-* set-buffer-modified-p: Buffer Modification.
-* set-case-syntax: Case Tables.
-* set-case-syntax-delims: Case Tables.
-* set-case-syntax-pair: Case Tables.
-* set-case-table: Case Tables.
-* set-category-table: Category Tables.
-* set-charset-ccl-program: Charset Property Functions.
-* set-coding-category-system: Detection of Textual Encoding.
-* set-coding-priority-list: Detection of Textual Encoding.
-* set-console-type-image-conversion-list: Image Instantiator Conversion.
-* set-default: Default Value.
-* set-default-file-modes: Changing File Attributes.
-* set-default-toolbar-position: Specifying the Toolbar.
-* set-device-baud-rate <1>: Terminal Output.
-* set-device-baud-rate: Console and Device I/O.
-* set-extent-begin-glyph: Extent Properties.
-* set-extent-begin-glyph-layout: Extent Properties.
-* set-extent-end-glyph: Extent Properties.
-* set-extent-end-glyph-layout: Extent Properties.
-* set-extent-endpoints: Extent Endpoints.
-* set-extent-face: Extent Properties.
-* set-extent-initial-redisplay-function: Extent Properties.
-* set-extent-keymap: Extent Properties.
-* set-extent-mouse-face: Extent Properties.
-* set-extent-parent: Extent Parents.
-* set-extent-priority: Extent Properties.
-* set-extent-properties: Extent Properties.
-* set-extent-property: Extent Properties.
-* set-face-background: Face Convenience Functions.
-* set-face-background-pixmap: Face Convenience Functions.
-* set-face-font: Face Convenience Functions.
-* set-face-foreground: Face Convenience Functions.
-* set-face-property: Face Properties.
-* set-face-underline-p: Face Convenience Functions.
-* set-file-modes: Changing File Attributes.
-* set-frame-configuration: Frame Configurations.
-* set-frame-pointer: Mouse Pointer.
-* set-frame-position: Size and Position.
-* set-frame-properties: Property Access.
-* set-frame-property: Property Access.
-* set-frame-size: Size and Position.
-* set-glyph-baseline: Glyph Convenience Functions.
-* set-glyph-contrib-p: Glyph Convenience Functions.
-* set-glyph-face: Glyph Convenience Functions.
-* set-glyph-image: Glyph Convenience Functions.
-* set-glyph-property: Glyph Properties.
-* set-input-mode: Input Modes.
-* set-keymap-default-binding: Inheritance and Keymaps.
-* set-keymap-name: Creating Keymaps.
-* set-keymap-parents: Inheritance and Keymaps.
-* set-keymap-prompt: Other Keymap Functions.
-* set-left-margin: Margins.
-* set-mark: The Mark.
-* set-marker: Changing Markers.
-* set-match-data: Entire Match Data.
-* set-menubar: Menubar.
-* set-menubar-dirty-flag: Menubar.
-* set-process-buffer: Process Buffers.
-* set-process-filter: Filter Functions.
-* set-process-sentinel: Sentinels.
-* set-process-window-size: Process Window Size.
-* set-recent-keys-ring-size: Recording Input.
-* set-register: Registers.
-* set-right-margin: Margins.
-* set-specifier: Adding Specifications.
-* set-standard-case-table: Case Tables.
-* set-syntax-table: Syntax Table Functions.
-* set-text-properties: Changing Properties.
-* set-tooltalk-message-attribute: Elisp Interface for Sending Messages.
-* set-visited-file-modtime: Modification Time.
-* set-visited-file-name: Buffer File Name.
-* set-weak-list-list: Weak Lists.
-* set-window-buffer: Buffers and Windows.
-* set-window-buffer-dedicated: Choosing Window.
-* set-window-configuration: Window Configurations.
-* set-window-dedicated-p: Choosing Window.
-* set-window-hscroll: Horizontal Scrolling.
-* set-window-point: Window Point.
-* set-window-start: Window Start.
-* setcar: Setcar.
-* setcdr: Setcdr.
-* setenv: System Environment.
-* setplist: Object Plists.
-* setprv: System Environment.
-* setq: Setting Variables.
-* setq-default: Default Value.
-* sets: Sets And Lists.
-* setting modes of files: Changing File Attributes.
-* setting-constant: Constant Variables.
-* seventh: List Elements.
-* sexp motion: List Motion.
-* shadowing of variables: Local Variables.
-* shallow binding: Impl of Scope.
-* shared-lisp-mode-map: Standard Keymaps.
-* Shell mode modeline-format: Modeline Data.
-* shell-command-history: Minibuffer History.
-* shrink-window: Resizing Windows.
-* shrink-window-horizontally: Resizing Windows.
-* shrink-window-pixels: Resizing Windows.
-* side effect: Intro Eval.
-* signal: Signaling Errors.
-* signal-error: Signaling Errors.
-* signal-process: Signals to Processes.
-* signaling errors: Signaling Errors.
-* signals: Signals to Processes.
-* sin: Math Functions.
-* single-key-description: Describing Characters.
-* sinh: Math Functions.
-* sit-for: Waiting.
-* site-init.el: Building XEmacs.
-* site-load.el: Building XEmacs.
-* site-run-file: Init File.
-* site-start.el: Start-up Summary.
-* sixth: List Elements.
-* size of frame: Size and Position.
-* size of window: Size of Window.
-* skip-chars-backward: Skipping Characters.
-* skip-chars-forward: Skipping Characters.
-* skip-syntax-backward: Motion and Syntax.
-* skip-syntax-forward: Motion and Syntax.
-* skipping characters: Skipping Characters.
-* skipping comments: Parsing Expressions.
-* sleep-for: Waiting.
-* Snarf-documentation: Accessing Documentation.
-* sort: Rearrangement.
-* sort-columns: Sorting.
-* sort-fields: Sorting.
-* sort-lines: Sorting.
-* sort-numeric-fields: Sorting.
-* sort-pages: Sorting.
-* sort-paragraphs: Sorting.
-* sort-regexp-fields: Sorting.
-* sort-subr: Sorting.
-* sorting lists: Rearrangement.
-* sorting text: Sorting.
-* sound: Beeping.
-* sound-alist: Beeping.
-* special: Major Mode Conventions.
-* special form descriptions: A Sample Function Description.
-* special form evaluation: Special Forms.
-* special forms: Primitive Function Type.
-* special forms (Edebug): Instrumenting.
-* special forms for control structures: Control Structures.
-* special-display-buffer-names: Choosing Window.
-* special-display-frame-plist: Choosing Window.
-* special-display-function: Choosing Window.
-* special-display-popup-frame: Choosing Window.
-* special-display-regexps: Choosing Window.
-* specification (in a specifier): Specifiers In-Depth.
-* specifier: Specifiers.
-* specifier type: Specifier Type.
-* specifier, domain: Specifiers In-Depth.
-* specifier, fallback: Specifier Instancing.
-* specifier, inst-list: Specifiers In-Depth.
-* specifier, inst-pair: Specifiers In-Depth.
-* specifier, instance: Specifiers In-Depth.
-* specifier, instancing: Specifiers In-Depth.
-* specifier, instantiator: Specifiers In-Depth.
-* specifier, locale: Specifiers In-Depth.
-* specifier, specification: Specifiers In-Depth.
-* specifier, tag: Specifiers In-Depth.
-* specifier, tag set: Specifiers In-Depth.
-* specifier-fallback: Retrieving Specifications.
-* specifier-instance: Specifier Instancing Functions.
-* specifier-instance-from-inst-list: Specifier Instancing Functions.
-* specifier-locale-type-from-locale: Other Specification Functions.
-* specifier-spec-list: Retrieving Specifications.
-* specifier-specs: Retrieving Specifications.
-* specifier-tag-list: Specifier Tag Functions.
-* specifier-tag-predicate: Specifier Tag Functions.
-* specifier-type: Specifier Types.
-* specifierp: Specifiers.
-* speedups: Compilation Tips.
-* splicing (with backquote): Backquote.
-* split-height-threshold: Choosing Window.
-* split-line: Commands for Insertion.
-* split-path: Regexp Search.
-* split-string: Regexp Search.
-* split-window: Splitting Windows.
-* split-window-horizontally: Splitting Windows.
-* split-window-vertically: Splitting Windows.
-* splitting windows: Splitting Windows.
-* sqrt: Math Functions.
-* stable sort: Rearrangement.
-* standard regexps used in editing: Standard Regexps.
-* standard-case-table: Case Tables.
-* standard-category-table: Category Tables.
-* standard-input: Input Functions.
-* standard-output: Output Variables.
-* standard-syntax-table: Standard Syntax Tables.
-* standards of coding style: Tips.
-* start up of XEmacs: Start-up Summary.
-* start-process: Asynchronous Processes.
-* start-process-shell-command: Asynchronous Processes.
-* startup.el: Start-up Summary.
-* stop points: Using Edebug.
-* stop-process: Signals to Processes.
-* stopping an infinite loop: Infinite Loops.
-* stopping on events: Global Break Condition.
-* store-match-data: Entire Match Data.
-* stream (for printing): Output Streams.
-* stream (for reading): Input Streams.
-* string: Creating Strings.
-* string equality: Text Comparison.
-* string in keymap: Key Lookup.
-* string input stream: Input Streams.
-* string length: Sequence Functions.
-* string length, maximum when printing: Output Variables.
-* string properties: String Properties.
-* string search: String Search.
-* string to character: String Conversion.
-* string to number: String Conversion.
-* string to object: Input Functions.
-* string, writing a doc string: Documentation Basics.
-* string-equal: Text Comparison.
-* string-lessp: Text Comparison.
-* string-match: Regexp Search.
-* string-modified-tick: Modifying Strings.
-* string-to-char: String Conversion.
-* string-to-int: String Conversion.
-* string-to-number: String Conversion.
-* string<: Text Comparison.
-* string=: Text Comparison.
-* stringp: Predicates for Strings.
-* strings: Strings and Characters.
-* strings, formatting them: Formatting Strings.
-* strings, modifying: Modifying Strings.
-* string quote: Syntax Class Table.
-* subprocess: Processes.
-* subr: What Is a Function.
-* subrp: What Is a Function.
-* subsidiary-coding-system: Basic Coding System Functions.
-* subst-char-in-region: Substitution.
-* substitute-command-keys: Keys in Documentation.
-* substitute-in-file-name: File Name Expansion.
-* substitute-key-definition: Changing Key Bindings.
-* substituting keys in documentation: Keys in Documentation.
-* substring: Creating Strings.
-* subwindow type: Subwindow Type.
-* subwindow-image-instance-p: Image Instance Types.
-* subwindowp: Subwindows.
-* suppress-keymap: Changing Key Bindings.
-* suspend (cf. no-redraw-on-reenter): Refresh Screen.
-* suspend evaluation: Recursive Editing.
-* suspend-emacs: Suspending XEmacs.
-* suspend-hook: Suspending XEmacs.
-* suspend-resume-hook: Suspending XEmacs.
-* suspending XEmacs: Suspending XEmacs.
-* switch-to-buffer: Displaying Buffers.
-* switch-to-buffer-other-window: Displaying Buffers.
-* switches on command line: Command Line Arguments.
-* switching to a buffer: Displaying Buffers.
-* symbol: Symbols.
-* symbol components: Symbol Components.
-* symbol equality: Creating Symbols.
-* symbol evaluation: Symbol Forms.
-* symbol function indirection: Function Indirection.
-* symbol in keymap: Key Lookup.
-* symbol name hashing: Creating Symbols.
-* symbol-function: Function Cells.
-* symbol-name: Creating Symbols.
-* symbol-plist: Object Plists.
-* symbol-value: Accessing Variables.
-* symbolp: Symbols.
-* symbol constituent: Syntax Class Table.
-* synchronous subprocess: Synchronous Processes.
-* syntax classes: Syntax Descriptors.
-* syntax descriptor: Syntax Descriptors.
-* syntax error (Edebug): Backtracking.
-* syntax flags: Syntax Flags.
-* syntax for characters: Character Type.
-* syntax table: Syntax Tables.
-* syntax table example: Example Major Modes.
-* syntax table internals: Syntax Table Internals.
-* syntax tables in modes: Major Mode Conventions.
-* syntax-table: Syntax Table Functions.
-* syntax-table-p: Syntax Basics.
-* system-configuration: System Environment.
-* system-name: System Environment.
-* system-type: System Environment.
-* t: Constant Variables.
-* t and truth: nil and t.
-* t input stream: Input Streams.
-* t output stream: Output Streams.
-* tab: Character Type.
-* tab deletion: Deletion.
-* tab-stop-list: Indent Tabs.
-* tab-to-tab-stop: Indent Tabs.
-* tab-width: Usual Display.
-* tabs stops for indentation: Indent Tabs.
-* tag (in a specifier): Specifiers In-Depth.
-* tag on run time stack: Catch and Throw.
-* tag set (in a specifier): Specifiers In-Depth.
-* tan: Math Functions.
-* tanh: Math Functions.
-* TCP: Network.
-* temacs: Building XEmacs.
-* temp-buffer-show-function: Temporary Displays.
-* temp-directory: Unique File Names.
-* tenth: List Elements.
-* TERM environment variable: Terminal-Specific.
-* term-file-prefix: Terminal-Specific.
-* term-setup-hook: Terminal-Specific.
-* Termcap: Terminal-Specific.
-* terminal frame <1>: Frames.
-* terminal frame: Basic Windows.
-* terminal input: Terminal Input.
-* terminal input modes: Input Modes.
-* terminal output: Terminal Output.
-* terminal-device: Console Types and Device Classes.
-* terminal-specific initialization: Terminal-Specific.
-* terminate keyboard macro: Peeking and Discarding.
-* termscript file: Terminal Output.
-* terpri: Output Functions.
-* testing types: Type Predicates.
-* text: Text.
-* text files and binary files: Files and MS-DOS.
-* text insertion: Insertion.
-* text parsing: Syntax Tables.
-* text properties: Text Properties.
-* text properties in files: Saving Properties.
-* text-char-description: Describing Characters.
-* text-image-instance-p: Image Instance Types.
-* text-mode-abbrev-table: Standard Abbrev Tables.
-* text-mode-map: Standard Keymaps.
-* text-mode-syntax-table: Standard Syntax Tables.
-* text-pointer-glyph: Mouse Pointer.
-* text-properties-at: Examining Properties.
-* text-property-any: Property Search.
-* text-property-not-all: Property Search.
-* third: List Elements.
-* this-command: Command Loop Info.
-* this-command-keys: Command Loop Info.
-* throw: Catch and Throw.
-* throw example: Recursive Editing.
-* tiled windows: Basic Windows.
-* timeout-event-p: Event Predicates.
-* timing programs: Compilation Tips.
-* tips: Tips.
-* toggle-read-only: Read Only Buffers.
-* toolbar: Toolbar.
-* toolbar button type: Toolbar Button Type.
-* toolbar-buttons-captioned-p: Other Toolbar Variables.
-* toolbar-make-button-list: Toolbar Descriptor Format.
-* toolbar-map <1>: Standard Keymaps.
-* toolbar-map: Active Keymaps.
-* toolbar-pointer-glyph: Mouse Pointer.
-* toolbar-specifier-p <1>: Specifier Types.
-* toolbar-specifier-p: Specifying the Toolbar.
-* ToolTalk: ToolTalk Support.
-* ToolTalk message: Sending Messages.
-* ToolTalk pattern: Receiving Messages.
-* top-level: Recursive Editing.
-* top-level form: Loading.
-* top-toolbar: Specifying the Toolbar.
-* top-toolbar-height: Other Toolbar Variables.
-* top-toolbar-visible-p: Other Toolbar Variables.
-* tq-close: Transaction Queues.
-* tq-create: Transaction Queues.
-* tq-enqueue: Transaction Queues.
-* tracing: Tracing.
-* transaction queue: Transaction Queues.
-* transcendental functions: Math Functions.
-* translate-region: Substitution.
-* translating input events: Translating Input.
-* transpose-regions: Transposition.
-* true: nil and t.
-* truename (of file): Truenames.
-* truncate: Numeric Conversions.
-* truncate-lines: Truncation.
-* truncate-partial-width-windows: Truncation.
-* truncation-glyph: Redisplay Glyphs.
-* truth value: nil and t.
-* try-completion: Basic Completion.
-* two's complement: Integer Basics.
-* type: Lisp Data Types.
-* type checking: Type Predicates.
-* type predicates: Type Predicates.
-* type-of: Type Predicates.
-* unbinding keys: Key Binding Commands.
-* undefined: Functions for Key Lookup.
-* undefined in keymap: Key Lookup.
-* undefined key: Keymap Terminology.
-* undo avoidance: Substitution.
-* undo-boundary: Undo.
-* undo-limit: Maintaining Undo.
-* undo-strong-limit: Maintaining Undo.
-* unexec: Building XEmacs.
-* unhandled-file-name-directory: Magic File Names.
-* unintern: Creating Symbols.
-* uninterned symbol: Creating Symbols.
-* uninterned symbols, printing: Output Variables.
-* unique extents: Duplicable Extents.
-* universal-argument: Prefix Command Arguments.
-* unload-feature: Unloading.
-* unloading: Unloading.
-* unlock-buffer: File Locks.
-* unmap-frame-hook: Frame Hooks.
-* unread-command-event: Peeking and Discarding.
-* unread-command-events: Peeking and Discarding.
-* unreading: Input Streams.
-* unregister-tooltalk-pattern: Elisp Interface for Receiving Messages.
-* unwind-protect: Cleanups.
-* unwinding: Cleanups.
-* up-list: List Motion.
-* upcase: Character Case.
-* upcase-region: Case Changes.
-* upcase-word: Case Changes.
-* update display: Refresh Screen.
-* update-directory-autoloads: Autoload.
-* update-file-autoloads: Autoload.
-* upper case: Character Case.
-* upper case key sequence: Key Sequence Input.
-* use-global-map: Active Keymaps.
-* use-hard-newlines: Filling.
-* use-left-overflow: Margin Primitives.
-* use-local-map: Active Keymaps.
-* use-right-overflow: Margin Primitives.
-* user name completion subroutines: User Name Completion.
-* user option: Defining Variables.
-* user-defined error: Error Symbols.
-* user-full-name: User Identification.
-* user-home-directory: User Identification.
-* user-login-name: User Identification.
-* user-mail-address: User Identification.
-* user-name-all-completions: User Name Completion.
-* user-name-completion: User Name Completion.
-* user-name-completion-1: User Name Completion.
-* user-real-login-name: User Identification.
-* user-real-uid: User Identification.
-* user-uid: User Identification.
-* user-variable-p: Defining Variables.
-* user-variable-p example: High-Level Completion.
-* valid-char-table-type-p: Char Table Types.
-* valid-char-table-value-p: Working With Char Tables.
-* valid-device-class-p: Console Types and Device Classes.
-* valid-device-type-p: Console Types and Device Classes.
-* valid-glyph-type-p: Glyph Types.
-* valid-image-instance-type-p: Image Instance Types.
-* valid-image-instantiator-format-p: Image Specifiers.
-* valid-inst-list-p: Specifier Validation Functions.
-* valid-instantiator-p: Specifier Validation Functions.
-* valid-plist-p: Property Lists.
-* valid-spec-list-p: Specifier Validation Functions.
-* valid-specifier-domain-p: Specifier Validation Functions.
-* valid-specifier-locale-p: Specifier Validation Functions.
-* valid-specifier-locale-type-p: Specifier Validation Functions.
-* valid-specifier-tag-p <1>: Specifier Validation Functions.
-* valid-specifier-tag-p: Specifier Tag Functions.
-* valid-specifier-tag-set-p: Specifier Tag Functions.
-* valid-specifier-type-p: Specifier Validation Functions.
-* value cell: Symbol Components.
-* value of expression: Evaluation.
-* values: Eval.
-* variable: Variables.
-* variable aliases: Variable Aliases.
-* variable definition: Defining Variables.
-* variable descriptions: A Sample Variable Description.
-* variable limit error: Local Variables.
-* variable-alias: Variable Aliases.
-* variable-documentation: Documentation Basics.
-* variable-obsoleteness-doc: Obsoleteness.
-* variables, buffer-local: Buffer-Local Variables.
-* variables, indirect: Variable Aliases.
-* vc-mode: Modeline Variables.
-* vconcat: Vector Functions.
-* vector <1>: Vector Functions.
-* vector: Vectors.
-* vector evaluation: Self-Evaluating Forms.
-* vector length: Sequence Functions.
-* vectorp: Vector Functions.
-* verify-visited-file-modtime: Modification Time.
-* version number (in file name): File Name Components.
-* version-control: Numbered Backups.
-* vertical scrolling: Vertical Scrolling.
-* vertical tab: Character Type.
-* vertical-motion: Screen Lines.
-* vertical-motion-pixels: Screen Lines.
-* view-file: Visiting Functions.
-* view-mode-map: Standard Keymaps.
-* view-register: Registers.
-* visible frame: Visibility of Frames.
-* visible-bell: Beeping.
-* visible-frame-list: Finding All Frames.
-* visited file: Buffer File Name.
-* visited file mode: Auto Major Mode.
-* visited-file-modtime: Modification Time.
-* visiting files: Visiting Files.
-* void function: Function Indirection.
-* void function cell: Function Cells.
-* void variable: Void Variables.
-* void-function: Function Cells.
-* void-variable: Void Variables.
-* waiting: Waiting.
-* waiting for command key input: Peeking and Discarding.
-* waiting-for-user-input-p: Sentinels.
-* wakeup: Subprocess Creation.
-* walk-windows: Cyclic Window Ordering.
-* weak hash table: Weak Hash Tables.
-* weak list: Weak Lists.
-* weak list type: Weak List Type.
-* weak-list-list: Weak Lists.
-* weak-list-p: Weak Lists.
-* weak-list-type: Weak Lists.
-* where-is-internal: Scanning Keymaps.
-* while: Iteration.
-* whitespace: Character Type.
-* whitespace character: Syntax Class Table.
-* widen: Narrowing.
-* widening: Narrowing.
-* window: Basic Windows.
-* window configuration (Edebug): Edebug Display Update.
-* window configurations: Window Configurations.
-* window excursions: Excursions.
-* window ordering, cyclic: Cyclic Window Ordering.
-* window point: Window Point.
-* window position <1>: Position of Window.
-* window position: Window Point.
-* window resizing: Resizing Windows.
-* window size: Size of Window.
-* window size, changing: Resizing Windows.
-* window splitting: Splitting Windows.
-* window system types: Window-System Types.
-* window top line: Window Start.
-* window-buffer: Buffers and Windows.
-* window-configuration-p: Window Configurations.
-* window-dedicated-p: Choosing Window.
-* window-displayed-text-pixel-height: Size of Window.
-* window-end: Window Start.
-* window-frame: Frames and Windows.
-* window-height: Size of Window.
-* window-highest-p: Position of Window.
-* window-hscroll: Horizontal Scrolling.
-* window-left-margin-pixel-width: Margin Primitives.
-* window-live-p: Deleting Windows.
-* window-lowest-p: Position of Window.
-* window-min-height: Resizing Windows.
-* window-min-width: Resizing Windows.
-* window-minibuffer-p: Minibuffer Misc.
-* window-pixel-edges: Position of Window.
-* window-pixel-height: Size of Window.
-* window-pixel-width: Size of Window.
-* window-point: Window Point.
-* window-right-margin-pixel-width: Margin Primitives.
-* window-setup-hook: Terminal-Specific.
-* window-size-change-functions: Resizing Windows.
-* window-start: Window Start.
-* window-system objects: Faces and Window-System Objects.
-* window-text-area-pixel-edges: Position of Window.
-* window-text-area-pixel-height: Size of Window.
-* window-text-area-pixel-width: Size of Window.
-* window-width: Size of Window.
-* windowp: Basic Windows.
-* windows, controlling precisely: Buffers and Windows.
-* with-current-buffer: Excursions.
-* with-output-to-temp-buffer: Temporary Displays.
-* with-selected-frame: Input Focus.
-* with-temp-file: Excursions.
-* word search: String Search.
-* word-search-backward: String Search.
-* word-search-forward: String Search.
-* words-include-escapes: Word Motion.
-* word constituent: Syntax Class Table.
-* write-abbrev-file: Abbrev Files.
-* write-char: Output Functions.
-* write-contents-hooks: Saving Buffers.
-* write-file: Saving Buffers.
-* write-file-hooks: Saving Buffers.
-* write-region: Writing to Files.
-* write-region-annotate-functions: Saving Properties.
-* writing a documentation string: Documentation Basics.
-* wrong-number-of-arguments: Argument List.
-* wrong-type-argument: Type Predicates.
-* X: X-Windows.
-* X resource type: X Resource Type.
-* X window frame: Frames.
-* x-allow-sendevents: X Miscellaneous.
-* x-bitmap-file-path <1>: X Miscellaneous.
-* x-bitmap-file-path: Image Specifiers.
-* x-debug-events: X Miscellaneous.
-* x-debug-mode: X Miscellaneous.
-* x-disown-selection: X Selections.
-* x-display-visual-class: Server Data.
-* x-emacs-application-class: Resources.
-* x-find-larger-font: Font Instance Size.
-* x-find-smaller-font: Font Instance Size.
-* x-font-size: Font Instance Size.
-* x-get-cutbuffer: X Selections.
-* x-get-resource: Resources.
-* x-get-selection: X Selections.
-* x-grab-keyboard: Grabs.
-* x-grab-pointer: Grabs.
-* x-library-search-path: X Miscellaneous.
-* x-make-font-bold: Font Instance Characteristics.
-* x-make-font-bold-italic: Font Instance Characteristics.
-* x-make-font-italic: Font Instance Characteristics.
-* x-make-font-unbold: Font Instance Characteristics.
-* x-make-font-unitalic: Font Instance Characteristics.
-* x-own-selection: X Selections.
-* x-put-resource: Resources.
-* x-server-vendor: Server Data.
-* x-server-version: Server Data.
-* x-set-frame-icon-pixmap: Frame Titles.
-* x-store-cutbuffer: X Selections.
-* x-ungrab-keyboard: Grabs.
-* x-ungrab-pointer: Grabs.
-* x-valid-keysym-name-p: X Miscellaneous.
-* x-window-id: X Miscellaneous.
-* X-Windows: X-Windows.
-* XEmacs event standard notation: Describing Characters.
-* xpm-color-symbols: Image Specifiers.
-* y-or-n-p: Yes-or-No Queries.
-* y-or-n-p-maybe-dialog-box: Yes-or-No Queries.
-* yank: Yank Commands.
-* yank suppression: Changing Key Bindings.
-* yank-pop: Yank Commands.
-* yes-or-no questions: Yes-or-No Queries.
-* yes-or-no-p: Yes-or-No Queries.
-* yes-or-no-p-dialog-box: Yes-or-No Queries.
-* yes-or-no-p-maybe-dialog-box: Yes-or-No Queries.
-* zero-length extent: Extent Endpoints.
-* zerop: Predicates on Numbers.
-* zmacs-activate-region: The Region.
-* zmacs-activate-region-hook: The Region.
-* zmacs-deactivate-region: The Region.
-* zmacs-deactivate-region-hook: The Region.
-* zmacs-region-stays: The Region.
-* zmacs-regions: The Region.
-* zmacs-update-region: The Region.
-* zmacs-update-region-hook: The Region.
-* | in regexp: Syntax of Regexps.
+* Building XEmacs:: How to preload Lisp libraries into XEmacs.
+* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
+* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
+
+\1f
+File: lispref.info, Node: Building XEmacs, Next: Pure Storage, Up: Building XEmacs and Object Allocation
+
+Building XEmacs
+===============
+
+ This section explains the steps involved in building the XEmacs
+executable. You don't have to know this material to build and install
+XEmacs, since the makefiles do all these things automatically. This
+information is pertinent to XEmacs maintenance.
+
+ The `XEmacs Internals Manual' contains more information about this.
+
+ Compilation of the C source files in the `src' directory produces an
+executable file called `temacs', also called a "bare impure XEmacs".
+It contains the XEmacs Lisp interpreter and I/O routines, but not the
+editing commands.
+
+ Before XEmacs is actually usable, a number of Lisp files need to be
+loaded. These define all the editing commands, plus most of the startup
+code and many very basic Lisp primitives. This is accomplished by
+loading the file `loadup.el', which in turn loads all of the other
+standardly-loaded Lisp files.
+
+ It takes a substantial time to load the standard Lisp files.
+Luckily, you don't have to do this each time you run XEmacs; `temacs'
+can dump out an executable program called `xemacs' that has these files
+preloaded. `xemacs' starts more quickly because it does not need to
+load the files. This is the XEmacs executable that is normally
+installed.
+
+ To create `xemacs', use the command `temacs -batch -l loadup dump'.
+The purpose of `-batch' here is to tell `temacs' to run in
+non-interactive, command-line mode. (`temacs' can _only_ run in this
+fashion. Part of the code required to initialize frames and faces is
+in Lisp, and must be loaded before XEmacs is able to create any frames.)
+The argument `dump' tells `loadup.el' to dump a new executable named
+`xemacs'.
+
+ The dumping process is highly system-specific, and some operating
+systems don't support dumping. On those systems, you must start XEmacs
+with the `temacs -batch -l loadup run-temacs' command each time you use
+it. This takes a substantial time, but since you need to start Emacs
+once a day at most--or once a week if you never log out--the extra time
+is not too severe a problem. (In older versions of Emacs, you started
+Emacs from `temacs' using `temacs -l loadup'.)
+
+ You are free to start XEmacs directly from `temacs' if you want,
+even if there is already a dumped `xemacs'. Normally you wouldn't want
+to do that; but the Makefiles do this when you rebuild XEmacs using
+`make all-elc', which builds XEmacs and simultaneously compiles any
+out-of-date Lisp files. (You need `xemacs' in order to compile Lisp
+files. However, you also need the compiled Lisp files in order to dump
+out `xemacs'. If both of these are missing or corrupted, you are out
+of luck unless you're able to bootstrap `xemacs' from `temacs'. Note
+that `make all-elc' actually loads the alternative loadup file
+`loadup-el.el', which works like `loadup.el' but disables the
+pure-copying process and forces XEmacs to ignore any compiled Lisp
+files even if they exist.)
+
+ You can specify additional files to preload by writing a library
+named `site-load.el' that loads them. You may need to increase the
+value of `PURESIZE', in `src/puresize.h', to make room for the
+additional files. You should _not_ modify this file directly, however;
+instead, use the `--puresize' configuration option. (If you run out of
+pure space while dumping `xemacs', you will be told how much pure space
+you actually will need.) However, the advantage of preloading
+additional files decreases as machines get faster. On modern machines,
+it is often not advisable, especially if the Lisp code is on a file
+system local to the machine running XEmacs.
+
+ You can specify other Lisp expressions to execute just before dumping
+by putting them in a library named `site-init.el'. However, if they
+might alter the behavior that users expect from an ordinary unmodified
+XEmacs, it is better to put them in `default.el', so that users can
+override them if they wish. *Note Start-up Summary::.
+
+ Before `loadup.el' dumps the new executable, it finds the
+documentation strings for primitive and preloaded functions (and
+variables) in the file where they are stored, by calling
+`Snarf-documentation' (*note Accessing Documentation::). These strings
+were moved out of the `xemacs' executable to make it smaller. *Note
+Documentation Basics::.
+
+ - Function: dump-emacs to-file from-file
+ This function dumps the current state of XEmacs into an executable
+ file TO-FILE. It takes symbols from FROM-FILE (this is normally
+ the executable file `temacs').
+
+ If you use this function in an XEmacs that was already dumped, you
+ must set `command-line-processed' to `nil' first for good results.
+ *Note Command Line Arguments::.
+
+ - Function: run-emacs-from-temacs &rest args
+ This is the function that implements the `run-temacs' command-line
+ argument. It is called from `loadup.el' as appropriate. You
+ should most emphatically _not_ call this yourself; it will
+ reinitialize your XEmacs process and you'll be sorry.
+
+ - Command: emacs-version
+ This function returns a string describing the version of XEmacs
+ that is running. It is useful to include this string in bug
+ reports.
+
+ (emacs-version)
+ => "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29)
+ of Mon Apr 7 1997 on altair.xemacs.org"
+
+ Called interactively, the function prints the same information in
+ the echo area.
+
+ - Variable: emacs-build-time
+ The value of this variable is the time at which XEmacs was built
+ at the local site.
+
+ emacs-build-time "Mon Apr 7 20:28:52 1997"
+ =>
+
+ - Variable: emacs-version
+ The value of this variable is the version of Emacs being run. It
+ is a string, e.g. `"20.1 XEmacs Lucid"'.
+
+ The following two variables did not exist before FSF GNU Emacs
+version 19.23 and XEmacs version 19.10, which reduces their usefulness
+at present, but we hope they will be convenient in the future.
+
+ - Variable: emacs-major-version
+ The major version number of Emacs, as an integer. For XEmacs
+ version 20.1, the value is 20.
+ - Variable: emacs-minor-version
+ The minor version number of Emacs, as an integer. For XEmacs
+ version 20.1, the value is 1.
edit-faces'.
-3.3: The Modeline
-=================
-
\1f
File: xemacs-faq.info, Node: Q3.3.1, Next: Q3.3.2, Prev: Q3.2.6, Up: Customization
+3.3: The Modeline
+=================
+
Q3.3.1: How can I make the modeline go away?
--------------------------------------------
* Q6.3.2:: What are the differences between the various MS Windows emacsen?
* Q6.3.3:: What is the porting team doing at the moment?
+Troubleshooting:
+* Q6.4.1:: XEmacs won't start on Windows. (NEW)
+
\1f
File: xemacs-faq.info, Node: Q6.0.1, Next: Q6.0.2, Prev: MS Windows, Up: MS Windows
\1f
-File: xemacs-faq.info, Node: Q6.3.3, Prev: Q6.3.2, Up: MS Windows
+File: xemacs-faq.info, Node: Q6.3.3, Next: Q6.4.1, Prev: Q6.3.2, Up: MS Windows
Q6.3.3: What is the porting team doing at the moment?
-----------------------------------------------------
The porting team is continuing work on the MS Windows-specific code.
\1f
+File: xemacs-faq.info, Node: Q6.4.1, Prev: Q6.3.3, Up: MS Windows
+
+6.3: Troubleshooting
+====================
+
+Q6.4.1 XEmacs won't start on Windows. (NEW)
+-------------------------------------------
+
+ XEmacs relies on a process called "dumping" to generate a working
+executable. Under MS-Windows this process effectively fixes the memory
+addresses of information in the executable. When XEmacs starts up it
+tries to reserve these memory addresses so that the dumping process can
+be reversed - putting the information back at the correct addresses.
+Unfortunately some .dlls (For instance the soundblaster driver) occupy
+memory addresses that can conflict with those needed by the dumped
+XEmacs executable. In this instance XEmacs will fail to start without
+any explanation. Note that this is extremely machine specific.
+
+ Work is being done on fixes for 21.1.* that will make more
+intelligent guesses about which memory addresses will be free and so
+this should cure the problem for most people.
+
+ 21.2 implements "portable dumping" which will eliminate the problem
+altogether.
+
+\1f
File: xemacs-faq.info, Node: Current Events, Prev: MS Windows, Up: Top
7 What the Future Holds
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
+
+Format of Outlines
+..................
+
+ Outline mode assumes that the lines in the buffer are of two types:
+"heading lines" and "body lines". A heading line represents a topic in
+the outline. Heading lines start with one or more stars; the number of
+stars determines the depth of the heading in the outline structure.
+Thus, a heading line with one star is a major topic; all the heading
+lines with two stars between it and the next one-star heading are its
+subtopics; and so on. Any line that is not a heading line is a body
+line. Body lines belong to the preceding heading line. Here is an
+example:
+
+ * Food
+
+ This is the body,
+ which says something about the topic of food.
+
+ ** Delicious Food
+
+ This is the body of the second-level header.
+
+ ** Distasteful Food
+
+ This could have
+ a body too, with
+ several lines.
+
+ *** Dormitory Food
+
+ * Shelter
+
+ A second first-level topic with its header line.
+
+ A heading line together with all following body lines is called
+collectively an "entry". A heading line together with all following
+deeper heading lines and their body lines is called a "subtree".
+
+ You can customize the criterion for distinguishing heading lines by
+setting the variable `outline-regexp'. Any line whose beginning has a
+match for this regexp is considered a heading line. Matches that start
+within a line (not at the beginning) do not count. The length of the
+matching text determines the level of the heading; longer matches make
+a more deeply nested level. Thus, for example, if a text formatter has
+commands `@chapter', `@section' and `@subsection' to divide the
+document into chapters and sections, you can make those lines count as
+heading lines by setting `outline-regexp' to
+`"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words
+`chapter' and `section' are the same length, but by defining the regexp
+to match only `chap' we ensure that the length of the text matched on a
+chapter heading is shorter, so that Outline mode will know that
+sections are contained in chapters. This works as long as no other
+command starts with `@chap'.
+
+ Outline mode makes a line invisible by changing the newline before it
+into an ASCII Control-M (code 015). Most editing commands that work on
+lines treat an invisible line as part of the previous line because,
+strictly speaking, it is part of that line, since there is no longer a
+newline in between. When you save the file in Outline mode, Control-M
+characters are saved as newlines, so the invisible lines become ordinary
+lines in the file. Saving does not change the visibility status of a
+line inside Emacs.
+
+\1f
File: xemacs.info, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode
Outline Motion Commands
the value is a number, `C-M-q' need not recalculate indentation
for the following lines until the end of the list.
-\1f
-File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
-
-Customizing C Indentation
--------------------------
-
- Two variables control which commands perform C indentation and when.
-
- If `c-auto-newline' is non-`nil', newlines are inserted both before
-and after braces that you insert and after colons and semicolons.
-Correct C indentation is done on all the lines that are made this way.
-
- If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
-does indentation only if point is at the left margin or within the
-line's indentation. If there is non-whitespace to the left of point,
-<TAB> just inserts a tab character in the buffer. Normally, this
-variable is `nil', and <TAB> always reindents the current line.
-
- C does not have anything analogous to particular function names for
-which special forms of indentation are desirable. However, it has a
-different need for customization facilities: many different styles of C
-indentation are in common use.
-
- There are six variables you can set to control the style that Emacs C
-mode will use.
-
-`c-indent-level'
- Indentation of C statements within surrounding block. The
- surrounding block's indentation is the indentation of the line on
- which the open-brace appears.
-
-`c-continued-statement-offset'
- Extra indentation given to a substatement, such as the then-clause
- of an `if' or body of a `while'.
-
-`c-brace-offset'
- Extra indentation for lines that start with an open brace.
-
-`c-brace-imaginary-offset'
- An open brace following other text is treated as if it were this
- far to the right of the start of its line.
-
-`c-argdecl-indent'
- Indentation level of declarations of C function arguments.
-
-`c-label-offset'
- Extra indentation for a line that is a label, case, or default.
-
- The variable `c-indent-level' controls the indentation for C
-statements with respect to the surrounding block. In the example:
-
- {
- foo ();
-
-the difference in indentation between the lines is `c-indent-level'.
-Its standard value is 2.
-
- If the open-brace beginning the compound statement is not at the
-beginning of its line, the `c-indent-level' is added to the indentation
-of the line, not the column of the open-brace. For example,
-
- if (losing) {
- do_this ();
-
-One popular indentation style is that which results from setting
-`c-indent-level' to 8 and putting open-braces at the end of a line in
-this way. Another popular style prefers to put the open-brace on a
-separate line.
-
- In fact, the value of the variable `c-brace-imaginary-offset' is
-also added to the indentation of such a statement. Normally this
-variable is zero. Think of this variable as the imaginary position of
-the open brace, relative to the first non-blank character on the line.
-By setting the variable to 4 and `c-indent-level' to 0, you can get
-this style:
-
- if (x == y) {
- do_it ();
- }
-
- When `c-indent-level' is zero, the statements inside most braces
-line up exactly under the open brace. An exception are braces in column
-zero, like those surrounding a function's body. The statements inside
-those braces are not placed at column zero. Instead, `c-brace-offset'
-and `c-continued-statement-offset' (see below) are added to produce a
-typical offset between brace levels, and the statements are indented
-that far.
-
- `c-continued-statement-offset' controls the extra indentation for a
-line that starts within a statement (but not within parentheses or
-brackets). These lines are usually statements inside other statements,
-like the then-clauses of `if' statements and the bodies of `while'
-statements. The `c-continued-statement-offset' parameter determines
-the difference in indentation between the two lines in:
-
- if (x == y)
- do_it ();
-
-The default value for `c-continued-statement-offset' is 2. Some
-popular indentation styles correspond to a value of zero for
-`c-continued-statement-offset'.
-
- `c-brace-offset' is the extra indentation given to a line that
-starts with an open-brace. Its standard value is zero; compare:
-
- if (x == y)
- {
-
-with:
-
- if (x == y)
- do_it ();
-
-If you set `c-brace-offset' to 4, the first example becomes:
-
- if (x == y)
- {
-
- `c-argdecl-indent' controls the indentation of declarations of the
-arguments of a C function. It is absolute: argument declarations
-receive exactly `c-argdecl-indent' spaces. The standard value is 5 and
-results in code like this:
-
- char *
- index (string, char)
- char *string;
- int char;
-
- `c-label-offset' is the extra indentation given to a line that
-contains a label, a case statement, or a `default:' statement. Its
-standard value is -2 and results in code like this:
-
- switch (c)
- {
- case 'x':
-
-If `c-label-offset' were zero, the same code would be indented as:
-
- switch (c)
- {
- case 'x':
-
-This example assumes that the other variables above also have their
-default values.
-
- Using the indentation style produced by the default settings of the
-variables just discussed and putting open braces on separate lines
-produces clear and readable files. For an example, look at any of the C
-source files of XEmacs.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
+
+Customizing C Indentation
+-------------------------
+
+ Two variables control which commands perform C indentation and when.
+
+ If `c-auto-newline' is non-`nil', newlines are inserted both before
+and after braces that you insert and after colons and semicolons.
+Correct C indentation is done on all the lines that are made this way.
+
+ If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
+does indentation only if point is at the left margin or within the
+line's indentation. If there is non-whitespace to the left of point,
+<TAB> just inserts a tab character in the buffer. Normally, this
+variable is `nil', and <TAB> always reindents the current line.
+
+ C does not have anything analogous to particular function names for
+which special forms of indentation are desirable. However, it has a
+different need for customization facilities: many different styles of C
+indentation are in common use.
+
+ There are six variables you can set to control the style that Emacs C
+mode will use.
+
+`c-indent-level'
+ Indentation of C statements within surrounding block. The
+ surrounding block's indentation is the indentation of the line on
+ which the open-brace appears.
+
+`c-continued-statement-offset'
+ Extra indentation given to a substatement, such as the then-clause
+ of an `if' or body of a `while'.
+
+`c-brace-offset'
+ Extra indentation for lines that start with an open brace.
+
+`c-brace-imaginary-offset'
+ An open brace following other text is treated as if it were this
+ far to the right of the start of its line.
+
+`c-argdecl-indent'
+ Indentation level of declarations of C function arguments.
+
+`c-label-offset'
+ Extra indentation for a line that is a label, case, or default.
+
+ The variable `c-indent-level' controls the indentation for C
+statements with respect to the surrounding block. In the example:
+
+ {
+ foo ();
+
+the difference in indentation between the lines is `c-indent-level'.
+Its standard value is 2.
+
+ If the open-brace beginning the compound statement is not at the
+beginning of its line, the `c-indent-level' is added to the indentation
+of the line, not the column of the open-brace. For example,
+
+ if (losing) {
+ do_this ();
+
+One popular indentation style is that which results from setting
+`c-indent-level' to 8 and putting open-braces at the end of a line in
+this way. Another popular style prefers to put the open-brace on a
+separate line.
+
+ In fact, the value of the variable `c-brace-imaginary-offset' is
+also added to the indentation of such a statement. Normally this
+variable is zero. Think of this variable as the imaginary position of
+the open brace, relative to the first non-blank character on the line.
+By setting the variable to 4 and `c-indent-level' to 0, you can get
+this style:
+
+ if (x == y) {
+ do_it ();
+ }
+
+ When `c-indent-level' is zero, the statements inside most braces
+line up exactly under the open brace. An exception are braces in column
+zero, like those surrounding a function's body. The statements inside
+those braces are not placed at column zero. Instead, `c-brace-offset'
+and `c-continued-statement-offset' (see below) are added to produce a
+typical offset between brace levels, and the statements are indented
+that far.
+
+ `c-continued-statement-offset' controls the extra indentation for a
+line that starts within a statement (but not within parentheses or
+brackets). These lines are usually statements inside other statements,
+like the then-clauses of `if' statements and the bodies of `while'
+statements. The `c-continued-statement-offset' parameter determines
+the difference in indentation between the two lines in:
+
+ if (x == y)
+ do_it ();
+
+The default value for `c-continued-statement-offset' is 2. Some
+popular indentation styles correspond to a value of zero for
+`c-continued-statement-offset'.
+
+ `c-brace-offset' is the extra indentation given to a line that
+starts with an open-brace. Its standard value is zero; compare:
+
+ if (x == y)
+ {
+
+with:
+
+ if (x == y)
+ do_it ();
+
+If you set `c-brace-offset' to 4, the first example becomes:
+
+ if (x == y)
+ {
+
+ `c-argdecl-indent' controls the indentation of declarations of the
+arguments of a C function. It is absolute: argument declarations
+receive exactly `c-argdecl-indent' spaces. The standard value is 5 and
+results in code like this:
+
+ char *
+ index (string, char)
+ char *string;
+ int char;
+
+ `c-label-offset' is the extra indentation given to a line that
+contains a label, a case statement, or a `default:' statement. Its
+standard value is -2 and results in code like this:
+
+ switch (c)
+ {
+ case 'x':
+
+If `c-label-offset' were zero, the same code would be indented as:
+
+ switch (c)
+ {
+ case 'x':
+
+This example assumes that the other variables above also have their
+default values.
+
+ Using the indentation style produced by the default settings of the
+variables just discussed and putting open braces on separate lines
+produces clear and readable files. For an example, look at any of the C
+source files of XEmacs.
+
+\1f
File: xemacs.info, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs
Automatic Display of Matching Parentheses
`fortran-electric-line-number' to `nil'. Then inserting line numbers
is like inserting anything else.
-\1f
-File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent
-
-Syntactic Conventions
-.....................
-
- Fortran mode assumes that you follow certain conventions that
-simplify the task of understanding a Fortran program well enough to
-indent it properly:
-
- * Two nested `do' loops never share a `continue' statement.
-
- * The same character appears in column 5 of all continuation lines.
- It is the value of the variable `fortran-continuation-char'. By
- default, this character is `$'.
-
-If you fail to follow these conventions, the indentation commands may
-indent some lines unaesthetically. However, a correct Fortran program
-will retain its meaning when reindented even if the conventions are not
-followed.
-
-\1f
-File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent
-
-Variables for Fortran Indentation
-.................................
-
- Several additional variables control how Fortran indentation works.
-
-`fortran-do-indent'
- Extra indentation within each level of `do' statement (the default
- is 3).
-
-`fortran-if-indent'
- Extra indentation within each level of `if' statement (the default
- is 3).
-
-`fortran-continuation-indent'
- Extra indentation for bodies of continuation lines (the default is
- 5).
-
-`fortran-check-all-num-for-matching-do'
- If this is `nil', indentation assumes that each `do' statement
- ends on a `continue' statement. Therefore, when computing
- indentation for a statement other than `continue', it can save
- time by not checking for a `do' statement ending there. If this
- is non-`nil', indenting any numbered statement must check for a
- `do' that ends there. The default is `nil'.
-
-`fortran-minimum-statement-indent'
- Minimum indentation for Fortran statements. For standard Fortran,
- this is 6. Statement bodies are always indented at least this
- much.
-
-\1f
-File: xemacs.info, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran
-
-Comments
---------
-
- The usual Emacs comment commands assume that a comment can follow a
-line of code. In Fortran, the standard comment syntax requires an
-entire line to be just a comment. Therefore, Fortran mode replaces the
-standard Emacs comment commands and defines some new variables.
-
- Fortran mode can also handle a non-standard comment syntax where
-comments start with `!' and can follow other text. Because only some
-Fortran compilers accept this syntax, Fortran mode will not insert such
-comments unless you have specified to do so in advance by setting the
-variable `comment-start' to `"!"' (*note Variables::).
-
-`M-;'
- Align comment or insert new comment (`fortran-comment-indent').
-
-`C-x ;'
- Applies to nonstandard `!' comments only.
-
-`C-c ;'
- Turn all lines of the region into comments, or (with arg) turn
- them back into real code (`fortran-comment-region').
-
- `M-;' in Fortran mode is redefined as the command
-`fortran-comment-indent'. Like the usual `M-;' command, it recognizes
-an existing comment and aligns its text appropriately. If there is no
-existing comment, a comment is inserted and aligned.
-
- Inserting and aligning comments is not the same in Fortran mode as in
-other modes. When a new comment must be inserted, a full-line comment
-is inserted if the current line is blank. On a non-blank line, a
-non-standard `!' comment is inserted if you previously specified you
-wanted to use them. Otherwise a full-line comment is inserted on a new
-line before the current line.
-
- Non-standard `!' comments are aligned like comments in other
-languages, but full-line comments are aligned differently. In a
-standard full-line comment, the comment delimiter itself must always
-appear in column zero. What can be aligned is the text within the
-comment. You can choose from three styles of alignment by setting the
-variable `fortran-comment-indent-style' to one of these values:
-
-`fixed'
- The text is aligned at a fixed column, which is the value of
- `fortran-comment-line-column'. This is the default.
-
-`relative'
- The text is aligned as if it were a line of code, but with an
- additional `fortran-comment-line-column' columns of indentation.
-
-`nil'
- Text in full-line columns is not moved automatically.
-
- You can also specify the character to be used to indent within
-full-line comments by setting the variable `fortran-comment-indent-char'
-to the character you want to use.
-
- Fortran mode introduces two variables `comment-line-start' and
-`comment-line-start-skip', which do for full-line comments what
-`comment-start' and `comment-start-skip' do for ordinary text-following
-comments. Normally these are set properly by Fortran mode, so you do
-not need to change them.
-
- The normal Emacs comment command `C-x ;' has not been redefined. It
-can therefore be used if you use `!' comments, but is useless in
-Fortran mode otherwise.
-
- The command `C-c ;' (`fortran-comment-region') turns all the lines
-of the region into comments by inserting the string `C$$$' at the front
-of each one. With a numeric arg, the region is turned back into live
-code by deleting `C$$$' from the front of each line. You can control
-the string used for the comments by setting the variable
-`fortran-comment-region'. Note that here we have an example of a
-command and a variable with the same name; the two uses of the name
-never conflict because in Lisp and in Emacs it is always clear from the
-context which one is referred to.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent
+
+Syntactic Conventions
+.....................
+
+ Fortran mode assumes that you follow certain conventions that
+simplify the task of understanding a Fortran program well enough to
+indent it properly:
+
+ * Two nested `do' loops never share a `continue' statement.
+
+ * The same character appears in column 5 of all continuation lines.
+ It is the value of the variable `fortran-continuation-char'. By
+ default, this character is `$'.
+
+If you fail to follow these conventions, the indentation commands may
+indent some lines unaesthetically. However, a correct Fortran program
+will retain its meaning when reindented even if the conventions are not
+followed.
+
+\1f
+File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent
+
+Variables for Fortran Indentation
+.................................
+
+ Several additional variables control how Fortran indentation works.
+
+`fortran-do-indent'
+ Extra indentation within each level of `do' statement (the default
+ is 3).
+
+`fortran-if-indent'
+ Extra indentation within each level of `if' statement (the default
+ is 3).
+
+`fortran-continuation-indent'
+ Extra indentation for bodies of continuation lines (the default is
+ 5).
+
+`fortran-check-all-num-for-matching-do'
+ If this is `nil', indentation assumes that each `do' statement
+ ends on a `continue' statement. Therefore, when computing
+ indentation for a statement other than `continue', it can save
+ time by not checking for a `do' statement ending there. If this
+ is non-`nil', indenting any numbered statement must check for a
+ `do' that ends there. The default is `nil'.
+
+`fortran-minimum-statement-indent'
+ Minimum indentation for Fortran statements. For standard Fortran,
+ this is 6. Statement bodies are always indented at least this
+ much.
+
+\1f
+File: xemacs.info, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran
+
+Comments
+--------
+
+ The usual Emacs comment commands assume that a comment can follow a
+line of code. In Fortran, the standard comment syntax requires an
+entire line to be just a comment. Therefore, Fortran mode replaces the
+standard Emacs comment commands and defines some new variables.
+
+ Fortran mode can also handle a non-standard comment syntax where
+comments start with `!' and can follow other text. Because only some
+Fortran compilers accept this syntax, Fortran mode will not insert such
+comments unless you have specified to do so in advance by setting the
+variable `comment-start' to `"!"' (*note Variables::).
+
+`M-;'
+ Align comment or insert new comment (`fortran-comment-indent').
+
+`C-x ;'
+ Applies to nonstandard `!' comments only.
+
+`C-c ;'
+ Turn all lines of the region into comments, or (with arg) turn
+ them back into real code (`fortran-comment-region').
+
+ `M-;' in Fortran mode is redefined as the command
+`fortran-comment-indent'. Like the usual `M-;' command, it recognizes
+an existing comment and aligns its text appropriately. If there is no
+existing comment, a comment is inserted and aligned.
+
+ Inserting and aligning comments is not the same in Fortran mode as in
+other modes. When a new comment must be inserted, a full-line comment
+is inserted if the current line is blank. On a non-blank line, a
+non-standard `!' comment is inserted if you previously specified you
+wanted to use them. Otherwise a full-line comment is inserted on a new
+line before the current line.
+
+ Non-standard `!' comments are aligned like comments in other
+languages, but full-line comments are aligned differently. In a
+standard full-line comment, the comment delimiter itself must always
+appear in column zero. What can be aligned is the text within the
+comment. You can choose from three styles of alignment by setting the
+variable `fortran-comment-indent-style' to one of these values:
+
+`fixed'
+ The text is aligned at a fixed column, which is the value of
+ `fortran-comment-line-column'. This is the default.
+
+`relative'
+ The text is aligned as if it were a line of code, but with an
+ additional `fortran-comment-line-column' columns of indentation.
+
+`nil'
+ Text in full-line columns is not moved automatically.
+
+ You can also specify the character to be used to indent within
+full-line comments by setting the variable `fortran-comment-indent-char'
+to the character you want to use.
+
+ Fortran mode introduces two variables `comment-line-start' and
+`comment-line-start-skip', which do for full-line comments what
+`comment-start' and `comment-start-skip' do for ordinary text-following
+comments. Normally these are set properly by Fortran mode, so you do
+not need to change them.
+
+ The normal Emacs comment command `C-x ;' has not been redefined. It
+can therefore be used if you use `!' comments, but is useless in
+Fortran mode otherwise.
+
+ The command `C-c ;' (`fortran-comment-region') turns all the lines
+of the region into comments by inserting the string `C$$$' at the front
+of each one. With a numeric arg, the region is turned back into live
+code by deleting `C$$$' from the front of each line. You can control
+the string used for the comments by setting the variable
+`fortran-comment-region'. Note that here we have an example of a
+command and a variable with the same name; the two uses of the name
+never conflict because in Lisp and in Emacs it is always clear from the
+context which one is referred to.
+
+\1f
File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran
Columns
or changed packages.
-\1f
-File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages
-
- Source packages are available from the `packages/source-packages'
-subdirectory of your favorite XEmacs distribution site. Alternatively,
-they are available via CVS from `cvs.xemacs.org'. Look at
-`http://cvs.xemacs.org' for instructions.
-
-Prerequisites for Building Source Packages
-------------------------------------------
-
- You must have GNU `cp', GNU `install' (or a BSD compatible `install'
-program) GNU `make' (3.75 or later preferred), `makeinfo' (1.68 from
-`texinfo-3.11' or later required), GNU `tar' and XEmacs 21.0. The
-source packages will untar into a correct directory structure. At the
-top level you must have `XEmacs.rules' and `package-compile.el'. These
-files are available from the XEmacs FTP site from the same place you
-obtained your source package distributions.
-
-What You Can Do With Source Packages
-------------------------------------
-
- NB: A global build operation doesn't exist yet as of 13 January
-1998.
-
- Source packages are most useful for creating XEmacs package tarballs
-for installation into your own XEmacs installations or for distributing
-to others.
-
- Supported operations from `make' are:
-
-`clean'
- Remove all built files except `auto-autoloads.el' and
- `custom-load.el'.
-
-`distclean'
- Remove XEmacs backups as well as the files deleted by `make clean'.
-
-`all'
- Bytecompile all files, build and bytecompile byproduct files like
- `auto-autoloads.el' and `custom-load.el'. Create info version of
- TeXinfo documentation if present.
-
-`srckit'
- Usually aliased to `make srckit-std'. This does a `make
- distclean' and creates a package source tarball in the staging
- directory. This is generally only of use for package maintainers.
-
-`binkit'
- May be aliased to `binkit-sourceonly', `binkit-sourceinfo',
- `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly'
- indicates there is nothing to install in a data directory or info
- directory. `sourceinfo' indicates that source and info files are
- to be installed. `sourcedata' indicates that source and etc
- (data) files are to be installed. `sourcedatainfo' indicates
- source, etc (data), and info files are to be installed. A few
- packages have needs beyond the basic templates so this is not yet
- complete.
-
-`dist'
- Runs the rules `srckit' followed by `binkit'. This is primarily
- of use by XEmacs maintainers producing files for distribution.
-
-\1f
-File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Packages, Up: Top
-
-Abbrevs
-*******
-
- An "abbrev" is a word which "expands" into some different text.
-Abbrevs are defined by the user to expand in specific ways. For
-example, you might define `foo' as an abbrev expanding to `find outer
-otter'. With this abbrev defined, you would be able to get `find outer
-otter ' into the buffer by typing `f o o <SPC>'.
-
- Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
-Disabling Abbrev mode does not cause abbrev definitions to be discarded,
-but they do not expand until Abbrev mode is enabled again. The command
-`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
-turns Abbrev mode on if the argument is positive, off otherwise. *Note
-Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on
-when the variable is non-`nil'. The variable `abbrev-mode'
-automatically becomes local to the current buffer when it is set.
-
- Abbrev definitions can be "mode-specific"--active only in one major
-mode. Abbrevs can also have "global" definitions that are active in
-all major modes. The same abbrev can have a global definition and
-various mode-specific definitions for different major modes. A
-mode-specific definition for the current major mode overrides a global
-definition.
-
- You can define Abbrevs interactively during an editing session. You
-can also save lists of abbrev definitions in files and reload them in
-later sessions. Some users keep extensive lists of abbrevs that they
-load in every session.
-
- A second kind of abbreviation facility is called the "dynamic
-expansion". Dynamic abbrev expansion happens only when you give an
-explicit command and the result of the expansion depends only on the
-current contents of the buffer. *Note Dynamic Abbrevs::.
-
-* Menu:
-
-* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
-* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
-* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
-* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
-* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
-
-\1f
-File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs
-
-Defining Abbrevs
-================
-
-`C-x a g'
- Define an abbrev to expand into some text before point
- (`add-global-abbrev').
-
-`C-x a l'
- Similar, but define an abbrev available only in the current major
- mode (`add-mode-abbrev').
-
-`C-x a i g'
- Define a word in the buffer as an abbrev
- (`inverse-add-global-abbrev').
-
-`C-x a i l'
- Define a word in the buffer as a mode-specific abbrev
- (`inverse-add-mode-abbrev').
-
-`M-x kill-all-abbrevs'
- After this command, no abbrev definitions remain in effect.
-
- The usual way to define an abbrev is to enter the text you want the
-abbrev to expand to, position point after it, and type `C-x a g'
-(`add-global-abbrev'). This reads the abbrev itself using the
-minibuffer, and then defines it as an abbrev for one or more words
-before point. Use a numeric argument to say how many words before point
-should be taken as the expansion. For example, to define the abbrev
-`foo' as in the example above, insert the text `find outer otter', then
-type
-`C-u 3 C-x a g f o o <RET>'.
-
- An argument of zero to `C-x a g' means to use the contents of the
-region as the expansion of the abbrev being defined.
-
- The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
-mode-specific abbrev. Mode-specific abbrevs are active only in a
-particular major mode. `C-x a l' defines an abbrev for the major mode
-in effect at the time `C-x a l' is typed. The arguments work the same
-way they do for `C-x a g'.
-
- If the text of an abbrev you want is already in the buffer instead of
-the expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
-instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
-instead of `C-x a l'. These commands are called "inverse" because they
-invert the meaning of the argument found in the buffer and the argument
-read using the minibuffer.
-
- To change the definition of an abbrev, just add the new definition.
-You will be asked to confirm if the abbrev has a prior definition. To
-remove an abbrev definition, give a negative argument to `C-x a g' or
-`C-x a l'. You must choose the command to specify whether to kill a
-global definition or a mode-specific definition for the current mode,
-since those two definitions are independent for one abbrev.
-
- `M-x kill-all-abbrevs' removes all existing abbrev definitions.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages
+
+ Source packages are available from the `packages/source-packages'
+subdirectory of your favorite XEmacs distribution site. Alternatively,
+they are available via CVS from `cvs.xemacs.org'. Look at
+`http://cvs.xemacs.org' for instructions.
+
+Prerequisites for Building Source Packages
+------------------------------------------
+
+ You must have GNU `cp', GNU `install' (or a BSD compatible `install'
+program) GNU `make' (3.75 or later preferred), `makeinfo' (1.68 from
+`texinfo-3.11' or later required), GNU `tar' and XEmacs 21.0. The
+source packages will untar into a correct directory structure. At the
+top level you must have `XEmacs.rules' and `package-compile.el'. These
+files are available from the XEmacs FTP site from the same place you
+obtained your source package distributions.
+
+What You Can Do With Source Packages
+------------------------------------
+
+ NB: A global build operation doesn't exist yet as of 13 January
+1998.
+
+ Source packages are most useful for creating XEmacs package tarballs
+for installation into your own XEmacs installations or for distributing
+to others.
+
+ Supported operations from `make' are:
+
+`clean'
+ Remove all built files except `auto-autoloads.el' and
+ `custom-load.el'.
+
+`distclean'
+ Remove XEmacs backups as well as the files deleted by `make clean'.
+
+`all'
+ Bytecompile all files, build and bytecompile byproduct files like
+ `auto-autoloads.el' and `custom-load.el'. Create info version of
+ TeXinfo documentation if present.
+
+`srckit'
+ Usually aliased to `make srckit-std'. This does a `make
+ distclean' and creates a package source tarball in the staging
+ directory. This is generally only of use for package maintainers.
+
+`binkit'
+ May be aliased to `binkit-sourceonly', `binkit-sourceinfo',
+ `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly'
+ indicates there is nothing to install in a data directory or info
+ directory. `sourceinfo' indicates that source and info files are
+ to be installed. `sourcedata' indicates that source and etc
+ (data) files are to be installed. `sourcedatainfo' indicates
+ source, etc (data), and info files are to be installed. A few
+ packages have needs beyond the basic templates so this is not yet
+ complete.
+
+`dist'
+ Runs the rules `srckit' followed by `binkit'. This is primarily
+ of use by XEmacs maintainers producing files for distribution.
+
+\1f
+File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Packages, Up: Top
+
+Abbrevs
+*******
+
+ An "abbrev" is a word which "expands" into some different text.
+Abbrevs are defined by the user to expand in specific ways. For
+example, you might define `foo' as an abbrev expanding to `find outer
+otter'. With this abbrev defined, you would be able to get `find outer
+otter ' into the buffer by typing `f o o <SPC>'.
+
+ Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
+Disabling Abbrev mode does not cause abbrev definitions to be discarded,
+but they do not expand until Abbrev mode is enabled again. The command
+`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
+turns Abbrev mode on if the argument is positive, off otherwise. *Note
+Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on
+when the variable is non-`nil'. The variable `abbrev-mode'
+automatically becomes local to the current buffer when it is set.
+
+ Abbrev definitions can be "mode-specific"--active only in one major
+mode. Abbrevs can also have "global" definitions that are active in
+all major modes. The same abbrev can have a global definition and
+various mode-specific definitions for different major modes. A
+mode-specific definition for the current major mode overrides a global
+definition.
+
+ You can define Abbrevs interactively during an editing session. You
+can also save lists of abbrev definitions in files and reload them in
+later sessions. Some users keep extensive lists of abbrevs that they
+load in every session.
+
+ A second kind of abbreviation facility is called the "dynamic
+expansion". Dynamic abbrev expansion happens only when you give an
+explicit command and the result of the expansion depends only on the
+current contents of the buffer. *Note Dynamic Abbrevs::.
+
+* Menu:
+
+* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
+* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
+* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
+* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
+* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
+
+\1f
+File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs
+
+Defining Abbrevs
+================
+
+`C-x a g'
+ Define an abbrev to expand into some text before point
+ (`add-global-abbrev').
+
+`C-x a l'
+ Similar, but define an abbrev available only in the current major
+ mode (`add-mode-abbrev').
+
+`C-x a i g'
+ Define a word in the buffer as an abbrev
+ (`inverse-add-global-abbrev').
+
+`C-x a i l'
+ Define a word in the buffer as a mode-specific abbrev
+ (`inverse-add-mode-abbrev').
+
+`M-x kill-all-abbrevs'
+ After this command, no abbrev definitions remain in effect.
+
+ The usual way to define an abbrev is to enter the text you want the
+abbrev to expand to, position point after it, and type `C-x a g'
+(`add-global-abbrev'). This reads the abbrev itself using the
+minibuffer, and then defines it as an abbrev for one or more words
+before point. Use a numeric argument to say how many words before point
+should be taken as the expansion. For example, to define the abbrev
+`foo' as in the example above, insert the text `find outer otter', then
+type
+`C-u 3 C-x a g f o o <RET>'.
+
+ An argument of zero to `C-x a g' means to use the contents of the
+region as the expansion of the abbrev being defined.
+
+ The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
+mode-specific abbrev. Mode-specific abbrevs are active only in a
+particular major mode. `C-x a l' defines an abbrev for the major mode
+in effect at the time `C-x a l' is typed. The arguments work the same
+way they do for `C-x a g'.
+
+ If the text of an abbrev you want is already in the buffer instead of
+the expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
+instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
+instead of `C-x a l'. These commands are called "inverse" because they
+invert the meaning of the argument found in the buffer and the argument
+read using the minibuffer.
+
+ To change the definition of an abbrev, just add the new definition.
+You will be asked to confirm if the abbrev has a prior definition. To
+remove an abbrev definition, give a negative argument to `C-x a g' or
+`C-x a l'. You must choose the command to specify whether to kill a
+global definition or a mode-specific definition for the current mode,
+since those two definitions are independent for one abbrev.
+
+ `M-x kill-all-abbrevs' removes all existing abbrev definitions.
+
+\1f
File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs
Controlling Abbrev Expansion
use of this command moves point through all the old marks on the ring,
one by one.
-\1f
-File: xemacs.info, Node: General Calendar, Next: LaTeX Calendar, Prev: Mark and Region, Up: Calendar/Diary
-
-Miscellaneous Calendar Commands
--------------------------------
-
-`p d'
- Display day-in-year (`calendar-print-day-of-year').
-
-`?'
- Briefly describe calendar commands (`describe-calendar-mode').
-
-`C-c C-l'
- Regenerate the calendar window (`redraw-calendar').
-
-`SPC'
- Scroll the next window (`scroll-other-window').
-
-`q'
- Exit from calendar (`exit-calendar').
-
- If you want to know how many days have elapsed since the start of
-the year, or the number of days remaining in the year, type the `p d'
-command (`calendar-print-day-of-year'). This displays both of those
-numbers in the echo area.
-
- To display a brief description of the calendar commands, type `?'
-(`describe-calendar-mode'). For a fuller description, type `C-h m'.
-
- You can use `SPC' (`scroll-other-window') to scroll the other
-window. This is handy when you display a list of holidays or diary
-entries in another window.
-
- If the calendar window text gets corrupted, type `C-c C-l'
-(`redraw-calendar') to redraw it. (This can only happen if you use
-non-Calendar-mode editing commands.)
-
- In Calendar mode, you can use `SPC' (`scroll-other-window') to
-scroll the other window. This is handy when you display a list of
-holidays or diary entries in another window.
-
- To exit from the calendar, type `q' (`exit-calendar'). This buries
-all buffers related to the calendar, selecting other buffers. (If a
-frame contains a dedicated calendar window, exiting from the calendar
-iconifies that frame.)
-
-\1f
-File: xemacs.info, Node: LaTeX Calendar, Next: Holidays, Prev: General Calendar, Up: Calendar/Diary
-
-LaTeX Calendar
-==============
-
- The Calendar LaTeX commands produce a buffer of LaTeX code that
-prints as a calendar. Depending on the command you use, the printed
-calendar covers the day, week, month or year that point is in.
-
-`t m'
- Generate a one-month calendar (`cal-tex-cursor-month').
-
-`t M'
- Generate a sideways-printing one-month calendar
- (`cal-tex-cursor-month-landscape').
-
-`t d'
- Generate a one-day calendar (`cal-tex-cursor-day').
-
-`t w 1'
- Generate a one-page calendar for one week (`cal-tex-cursor-week').
-
-`t w 2'
- Generate a two-page calendar for one week (`cal-tex-cursor-week2').
-
-`t w 3'
- Generate an ISO-style calendar for one week
- (`cal-tex-cursor-week-iso').
-
-`t w 4'
- Generate a calendar for one Monday-starting week
- (`cal-tex-cursor-week-monday').
-
-`t f w'
- Generate a Filofax-style two-weeks-at-a-glance calendar
- (`cal-tex-cursor-filofax-2week').
-
-`t f W'
- Generate a Filofax-style one-week-at-a-glance calendar
- (`cal-tex-cursor-filofax-week').
-
-`t y'
- Generate a calendar for one year (`cal-tex-cursor-year').
-
-`t Y'
- Generate a sideways-printing calendar for one year
- (`cal-tex-cursor-year-landscape').
-
-`t f y'
- Generate a Filofax-style calendar for one year
- (`cal-tex-cursor-filofax-year').
-
- Some of these commands print the calendar sideways (in "landscape
-mode"), so it can be wider than it is long. Some of them use Filofax
-paper size (3.75in x 6.75in). All of these commands accept a prefix
-argument which specifies how many days, weeks, months or years to print
-(starting always with the selected one).
-
- If the variable `cal-tex-holidays' is non-`nil' (the default), then
-the printed calendars show the holidays in `calendar-holidays'. If the
-variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary
-entries are included also (in weekly and monthly calendars only).
-
-\1f
-File: xemacs.info, Node: Holidays, Next: Sunrise/Sunset, Prev: LaTeX Calendar, Up: Calendar/Diary
-
-Holidays
---------
-
- The Emacs calendar knows about all major and many minor holidays,
-and can display them.
-
-`h'
- Display holidays for the selected date
- (`calendar-cursor-holidays').
-
-`Button2 Holidays'
- Display any holidays for the date you click on.
-
-`x'
- Mark holidays in the calendar window (`mark-calendar-holidays').
-
-`u'
- Unmark calendar window (`calendar-unmark').
-
-`a'
- List all holidays for the displayed three months in another window
- (`list-calendar-holidays').
-
-`M-x holidays'
- List all holidays for three months around today's date in another
- window.
-
-`M-x list-holidays'
- List holidays in another window for a specified range of years.
-
- To see if any holidays fall on a given date, position point on that
-date in the calendar window and use the `h' command. Alternatively,
-click on that date with `Button2' and then choose `Holidays' from the
-menu that appears. Either way, this displays the holidays for that
-date, in the echo area if they fit there, otherwise in a separate
-window.
-
- To view the distribution of holidays for all the dates shown in the
-calendar, use the `x' command. This displays the dates that are
-holidays in a different face (or places a `*' after these dates, if
-display with multiple faces is not available). The command applies both
-to the currently visible months and to other months that subsequently
-become visible by scrolling. To turn marking off and erase the current
-marks, type `u', which also erases any diary marks (*note Diary::).
-
- To get even more detailed information, use the `a' command, which
-displays a separate buffer containing a list of all holidays in the
-current three-month range. You can use <SPC> in the calendar window to
-scroll that list.
-
- The command `M-x holidays' displays the list of holidays for the
-current month and the preceding and succeeding months; this works even
-if you don't have a calendar window. If you want the list of holidays
-centered around a different month, use `C-u M-x holidays', which
-prompts for the month and year.
-
- The holidays known to Emacs include United States holidays and the
-major Christian, Jewish, and Islamic holidays; also the solstices and
-equinoxes.
-
- The command `M-x list-holidays' displays the list of holidays for a
-range of years. This function asks you for the starting and stopping
-years, and allows you to choose all the holidays or one of several
-categories of holidays. You can use this command even if you don't have
-a calendar window.
-
- The dates used by Emacs for holidays are based on _current
-practice_, not historical fact. Historically, for instance, the start
-of daylight savings time and even its existence have varied from year to
-year, but present United States law mandates that daylight savings time
-begins on the first Sunday in April. When the daylight savings rules
-are set up for the United States, Emacs always uses the present
-definition, even though it is wrong for some prior years.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: General Calendar, Next: LaTeX Calendar, Prev: Mark and Region, Up: Calendar/Diary
+
+Miscellaneous Calendar Commands
+-------------------------------
+
+`p d'
+ Display day-in-year (`calendar-print-day-of-year').
+
+`?'
+ Briefly describe calendar commands (`describe-calendar-mode').
+
+`C-c C-l'
+ Regenerate the calendar window (`redraw-calendar').
+
+`SPC'
+ Scroll the next window (`scroll-other-window').
+
+`q'
+ Exit from calendar (`exit-calendar').
+
+ If you want to know how many days have elapsed since the start of
+the year, or the number of days remaining in the year, type the `p d'
+command (`calendar-print-day-of-year'). This displays both of those
+numbers in the echo area.
+
+ To display a brief description of the calendar commands, type `?'
+(`describe-calendar-mode'). For a fuller description, type `C-h m'.
+
+ You can use `SPC' (`scroll-other-window') to scroll the other
+window. This is handy when you display a list of holidays or diary
+entries in another window.
+
+ If the calendar window text gets corrupted, type `C-c C-l'
+(`redraw-calendar') to redraw it. (This can only happen if you use
+non-Calendar-mode editing commands.)
+
+ In Calendar mode, you can use `SPC' (`scroll-other-window') to
+scroll the other window. This is handy when you display a list of
+holidays or diary entries in another window.
+
+ To exit from the calendar, type `q' (`exit-calendar'). This buries
+all buffers related to the calendar, selecting other buffers. (If a
+frame contains a dedicated calendar window, exiting from the calendar
+iconifies that frame.)
+
+\1f
+File: xemacs.info, Node: LaTeX Calendar, Next: Holidays, Prev: General Calendar, Up: Calendar/Diary
+
+LaTeX Calendar
+==============
+
+ The Calendar LaTeX commands produce a buffer of LaTeX code that
+prints as a calendar. Depending on the command you use, the printed
+calendar covers the day, week, month or year that point is in.
+
+`t m'
+ Generate a one-month calendar (`cal-tex-cursor-month').
+
+`t M'
+ Generate a sideways-printing one-month calendar
+ (`cal-tex-cursor-month-landscape').
+
+`t d'
+ Generate a one-day calendar (`cal-tex-cursor-day').
+
+`t w 1'
+ Generate a one-page calendar for one week (`cal-tex-cursor-week').
+
+`t w 2'
+ Generate a two-page calendar for one week (`cal-tex-cursor-week2').
+
+`t w 3'
+ Generate an ISO-style calendar for one week
+ (`cal-tex-cursor-week-iso').
+
+`t w 4'
+ Generate a calendar for one Monday-starting week
+ (`cal-tex-cursor-week-monday').
+
+`t f w'
+ Generate a Filofax-style two-weeks-at-a-glance calendar
+ (`cal-tex-cursor-filofax-2week').
+
+`t f W'
+ Generate a Filofax-style one-week-at-a-glance calendar
+ (`cal-tex-cursor-filofax-week').
+
+`t y'
+ Generate a calendar for one year (`cal-tex-cursor-year').
+
+`t Y'
+ Generate a sideways-printing calendar for one year
+ (`cal-tex-cursor-year-landscape').
+
+`t f y'
+ Generate a Filofax-style calendar for one year
+ (`cal-tex-cursor-filofax-year').
+
+ Some of these commands print the calendar sideways (in "landscape
+mode"), so it can be wider than it is long. Some of them use Filofax
+paper size (3.75in x 6.75in). All of these commands accept a prefix
+argument which specifies how many days, weeks, months or years to print
+(starting always with the selected one).
+
+ If the variable `cal-tex-holidays' is non-`nil' (the default), then
+the printed calendars show the holidays in `calendar-holidays'. If the
+variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary
+entries are included also (in weekly and monthly calendars only).
+
+\1f
+File: xemacs.info, Node: Holidays, Next: Sunrise/Sunset, Prev: LaTeX Calendar, Up: Calendar/Diary
+
+Holidays
+--------
+
+ The Emacs calendar knows about all major and many minor holidays,
+and can display them.
+
+`h'
+ Display holidays for the selected date
+ (`calendar-cursor-holidays').
+
+`Button2 Holidays'
+ Display any holidays for the date you click on.
+
+`x'
+ Mark holidays in the calendar window (`mark-calendar-holidays').
+
+`u'
+ Unmark calendar window (`calendar-unmark').
+
+`a'
+ List all holidays for the displayed three months in another window
+ (`list-calendar-holidays').
+
+`M-x holidays'
+ List all holidays for three months around today's date in another
+ window.
+
+`M-x list-holidays'
+ List holidays in another window for a specified range of years.
+
+ To see if any holidays fall on a given date, position point on that
+date in the calendar window and use the `h' command. Alternatively,
+click on that date with `Button2' and then choose `Holidays' from the
+menu that appears. Either way, this displays the holidays for that
+date, in the echo area if they fit there, otherwise in a separate
+window.
+
+ To view the distribution of holidays for all the dates shown in the
+calendar, use the `x' command. This displays the dates that are
+holidays in a different face (or places a `*' after these dates, if
+display with multiple faces is not available). The command applies both
+to the currently visible months and to other months that subsequently
+become visible by scrolling. To turn marking off and erase the current
+marks, type `u', which also erases any diary marks (*note Diary::).
+
+ To get even more detailed information, use the `a' command, which
+displays a separate buffer containing a list of all holidays in the
+current three-month range. You can use <SPC> in the calendar window to
+scroll that list.
+
+ The command `M-x holidays' displays the list of holidays for the
+current month and the preceding and succeeding months; this works even
+if you don't have a calendar window. If you want the list of holidays
+centered around a different month, use `C-u M-x holidays', which
+prompts for the month and year.
+
+ The holidays known to Emacs include United States holidays and the
+major Christian, Jewish, and Islamic holidays; also the solstices and
+equinoxes.
+
+ The command `M-x list-holidays' displays the list of holidays for a
+range of years. This function asks you for the starting and stopping
+years, and allows you to choose all the holidays or one of several
+categories of holidays. You can use this command even if you don't have
+a calendar window.
+
+ The dates used by Emacs for holidays are based on _current
+practice_, not historical fact. Historically, for instance, the start
+of daylight savings time and even its existence have varied from year to
+year, but present United States law mandates that daylight savings time
+begins on the first Sunday in April. When the daylight savings rules
+are set up for the United States, Emacs always uses the present
+definition, even though it is wrong for some prior years.
+
+\1f
File: xemacs.info, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary
Times of Sunrise and Sunset
A similar normal hook, `today-invisible-calendar-hook' is run if the
current date is _not_ visible in the window.
-\1f
-File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
-
-Customizing the Holidays
-........................
-
- Emacs knows about holidays defined by entries on one of several
-lists. You can customize these lists of holidays to your own needs,
-adding or deleting holidays. The lists of holidays that Emacs uses are
-for general holidays (`general-holidays'), local holidays
-(`local-holidays'), Christian holidays (`christian-holidays'), Hebrew
-(Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays
-(`islamic-holidays'), and other holidays (`other-holidays').
-
- The general holidays are, by default, holidays common throughout the
-United States. To eliminate these holidays, set `general-holidays' to
-`nil'.
-
- There are no default local holidays (but sites may supply some). You
-can set the variable `local-holidays' to any list of holidays, as
-described below.
-
- By default, Emacs does not include all the holidays of the religions
-that it knows, only those commonly found in secular calendars. For a
-more extensive collection of religious holidays, you can set any (or
-all) of the variables `all-christian-calendar-holidays',
-`all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to
-`t'. If you want to eliminate the religious holidays, set any or all
-of the corresponding variables `christian-holidays', `hebrew-holidays',
-and `islamic-holidays' to `nil'.
-
- You can set the variable `other-holidays' to any list of holidays.
-This list, normally empty, is intended for individual use.
-
- Each of the lists (`general-holidays', `local-holidays',
-`christian-holidays', `hebrew-holidays', `islamic-holidays', and
-`other-holidays') is a list of "holiday forms", each holiday form
-describing a holiday (or sometimes a list of holidays).
-
- Here is a table of the possible kinds of holiday form. Day numbers
-and month numbers count starting from 1, but "dayname" numbers count
-Sunday as 0. The element STRING is always the name of the holiday, as
-a string.
-
-`(holiday-fixed MONTH DAY STRING)'
- A fixed date on the Gregorian calendar. MONTH and DAY are
- numbers, STRING is the name of the holiday.
-
-`(holiday-float MONTH DAYNAME K STRING)'
- The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for
- Sunday, and so on); negative K means count back from the end of
- the month. STRING is the name of the holiday.
-
-`(holiday-hebrew MONTH DAY STRING)'
- A fixed date on the Hebrew calendar. MONTH and DAY are numbers,
- STRING is the name of the holiday.
-
-`(holiday-islamic MONTH DAY STRING)'
- A fixed date on the Islamic calendar. MONTH and DAY are numbers,
- STRING is the name of the holiday.
-
-`(holiday-julian MONTH DAY STRING)'
- A fixed date on the Julian calendar. MONTH and DAY are numbers,
- STRING is the name of the holiday.
-
-`(holiday-sexp SEXP STRING)'
- A date calculated by the Lisp expression SEXP. The expression
- should use the variable `year' to compute and return the date of a
- holiday, or `nil' if the holiday doesn't happen this year. The
- value of SEXP must represent the date as a list of the form
- `(MONTH DAY YEAR)'. STRING is the name of the holiday.
-
-`(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)'
- A holiday that happens only if CONDITION is true.
-
-`(FUNCTION [ARGS])'
- A list of dates calculated by the function FUNCTION, called with
- arguments ARGS.
-
- For example, suppose you want to add Bastille Day, celebrated in
-France on July 14. You can do this by adding the following line to
-your `.emacs' file:
-
- (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
-
-The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the
-fourteenth day of the seventh month (July).
-
- Many holidays occur on a specific day of the week, at a specific time
-of month. Here is a holiday form describing Hurricane Supplication Day,
-celebrated in the Virgin Islands on the fourth Monday in August:
-
- (holiday-float 8 1 4 "Hurricane Supplication Day")
-
-Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
-Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
-the month (1 specifies the first occurrence, 2 the second occurrence,
--1 the last occurrence, -2 the second-to-last occurrence, and so on).
-
- You can specify holidays that occur on fixed days of the Hebrew,
-Islamic, and Julian calendars too. For example,
-
- (setq other-holidays
- '((holiday-hebrew 10 2 "Last day of Hanukkah")
- (holiday-islamic 3 12 "Mohammed's Birthday")
- (holiday-julian 4 2 "Jefferson's Birthday")))
-
-adds the last day of Hanukkah (since the Hebrew months are numbered with
-1 starting from Nisan), the Islamic feast celebrating Mohammed's
-birthday (since the Islamic months are numbered from 1 starting with
-Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
-Julian calendar.
-
- To include a holiday conditionally, use either Emacs Lisp's `if' or
-the `holiday-sexp' form. For example, American presidential elections
-occur on the first Tuesday after the first Monday in November of years
-divisible by 4:
-
- (holiday-sexp (if (= 0 (% year 4))
- (calendar-gregorian-from-absolute
- (1+ (calendar-dayname-on-or-before
- 1 (+ 6 (calendar-absolute-from-gregorian
- (list 11 1 year))))))
- "US Presidential Election"))
-
-or
-
- (if (= 0 (% displayed-year 4))
- (fixed 11
- (extract-calendar-day
- (calendar-gregorian-from-absolute
- (1+ (calendar-dayname-on-or-before
- 1 (+ 6 (calendar-absolute-from-gregorian
- (list 11 1 displayed-year)))))))
- "US Presidential Election"))
-
- Some holidays just don't fit into any of these forms because special
-calculations are involved in their determination. In such cases you
-must write a Lisp function to do the calculation. To include eclipses,
-for example, add `(eclipses)' to `other-holidays' and write an Emacs
-Lisp function `eclipses' that returns a (possibly empty) list of the
-relevant Gregorian dates among the range visible in the calendar
-window, with descriptive strings, like this:
-
- (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
-
-\1f
-File: xemacs.info, Node: Date Display Format, Next: Time Display Format, Prev: Holiday Customizing, Up: Calendar Customization
-
-Date Display Format
-...................
-
- You can customize the manner of displaying dates in the diary, in
-mode lines, and in messages by setting `calendar-date-display-form'.
-This variable holds a list of expressions that can involve the variables
-`month', `day', and `year', which are all numbers in string form, and
-`monthname' and `dayname', which are both alphabetic strings. In the
-American style, the default value of this list is as follows:
-
- ((if dayname (concat dayname ", ")) monthname " " day ", " year)
-
-while in the European style this value is the default:
-
- ((if dayname (concat dayname ", ")) day " " monthname " " year)
-
- + The ISO standard date representation is this:
-
- (year "-" month "-" day)
-
-This specifies a typical American format:
-
- (month "/" day "/" (substring year -2))
-
-\1f
-File: xemacs.info, Node: Time Display Format, Next: Daylight Savings, Prev: Date Display Format, Up: Calendar Customization
-
-Time Display Format
-...................
-
- The calendar and diary by default display times of day in the
-conventional American style with the hours from 1 through 12, minutes,
-and either `am' or `pm'. If you prefer the European style, also known
-in the US as military, in which the hours go from 00 to 23, you can
-alter the variable `calendar-time-display-form'. This variable is a
-list of expressions that can involve the variables `12-hours',
-`24-hours', and `minutes', which are all numbers in string form, and
-`am-pm' and `time-zone', which are both alphabetic strings. The
-default value of `calendar-time-display-form' is as follows:
-
- (12-hours ":" minutes am-pm
- (if time-zone " (") time-zone (if time-zone ")"))
-
-Here is a value that provides European style times:
-
- (24-hours ":" minutes
- (if time-zone " (") time-zone (if time-zone ")"))
-
-gives military-style times like `21:07 (UT)' if time zone names are
-defined, and times like `21:07' if they are not.
-
-\1f
-File: xemacs.info, Node: Daylight Savings, Next: Diary Customizing, Prev: Time Display Format, Up: Calendar Customization
-
-Daylight Savings Time
-.....................
-
- Emacs understands the difference between standard time and daylight
-savings time--the times given for sunrise, sunset, solstices,
-equinoxes, and the phases of the moon take that into account. The rules
-for daylight savings time vary from place to place and have also varied
-historically from year to year. To do the job properly, Emacs needs to
-know which rules to use.
-
- Some operating systems keep track of the rules that apply to the
-place where you are; on these systems, Emacs gets the information it
-needs from the system automatically. If some or all of this
-information is missing, Emacs fills in the gaps with the rules
-currently used in Cambridge, Massachusetts. If the resulting rules are
-not what you want, you can tell Emacs the rules to use by setting
-certain variables.
-
- If the default choice of rules is not appropriate for your location,
-you can tell Emacs the rules to use by setting the variables
-`calendar-daylight-savings-starts' and
-`calendar-daylight-savings-ends'. Their values should be Lisp
-expressions that refer to the variable `year', and evaluate to the
-Gregorian date on which daylight savings time starts or (respectively)
-ends, in the form of a list `(MONTH DAY YEAR)'. The values should be
-`nil' if your area does not use daylight savings time.
-
- Emacs uses these expressions to determine the starting date of
-daylight savings time for the holiday list and for correcting times of
-day in the solar and lunar calculations.
-
- The values for Cambridge, Massachusetts are as follows:
-
- (calendar-nth-named-day 1 0 4 year)
- (calendar-nth-named-day -1 0 10 year)
-
-That is, the first 0th day (Sunday) of the fourth month (April) in the
-year specified by `year', and the last Sunday of the tenth month
-(October) of that year. If daylight savings time were changed to start
-on October 1, you would set `calendar-daylight-savings-starts' to this:
-
- (list 10 1 year)
-
- For a more complex example, suppose daylight savings time begins on
-the first of Nisan on the Hebrew calendar. You should set
-`calendar-daylight-savings-starts' to this value:
-
- (calendar-gregorian-from-absolute
- (calendar-absolute-from-hebrew
- (list 1 1 (+ year 3760))))
-
-because Nisan is the first month in the Hebrew calendar and the Hebrew
-year differs from the Gregorian year by 3760 at Nisan.
-
- If there is no daylight savings time at your location, or if you want
-all times in standard time, set `calendar-daylight-savings-starts' and
-`calendar-daylight-savings-ends' to `nil'.
-
- The variable `calendar-daylight-time-offset' specifies the
-difference between daylight savings time and standard time, measured in
-minutes. The value for Cambridge, Massachusetts is 60.
-
- The two variables `calendar-daylight-savings-starts-time' and
-`calendar-daylight-savings-ends-time' specify the number of minutes
-after midnight local time when the transition to and from daylight
-savings time should occur. For Cambridge, Massachusetts both variables'
-values are 120.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
+
+Customizing the Holidays
+........................
+
+ Emacs knows about holidays defined by entries on one of several
+lists. You can customize these lists of holidays to your own needs,
+adding or deleting holidays. The lists of holidays that Emacs uses are
+for general holidays (`general-holidays'), local holidays
+(`local-holidays'), Christian holidays (`christian-holidays'), Hebrew
+(Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays
+(`islamic-holidays'), and other holidays (`other-holidays').
+
+ The general holidays are, by default, holidays common throughout the
+United States. To eliminate these holidays, set `general-holidays' to
+`nil'.
+
+ There are no default local holidays (but sites may supply some). You
+can set the variable `local-holidays' to any list of holidays, as
+described below.
+
+ By default, Emacs does not include all the holidays of the religions
+that it knows, only those commonly found in secular calendars. For a
+more extensive collection of religious holidays, you can set any (or
+all) of the variables `all-christian-calendar-holidays',
+`all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to
+`t'. If you want to eliminate the religious holidays, set any or all
+of the corresponding variables `christian-holidays', `hebrew-holidays',
+and `islamic-holidays' to `nil'.
+
+ You can set the variable `other-holidays' to any list of holidays.
+This list, normally empty, is intended for individual use.
+
+ Each of the lists (`general-holidays', `local-holidays',
+`christian-holidays', `hebrew-holidays', `islamic-holidays', and
+`other-holidays') is a list of "holiday forms", each holiday form
+describing a holiday (or sometimes a list of holidays).
+
+ Here is a table of the possible kinds of holiday form. Day numbers
+and month numbers count starting from 1, but "dayname" numbers count
+Sunday as 0. The element STRING is always the name of the holiday, as
+a string.
+
+`(holiday-fixed MONTH DAY STRING)'
+ A fixed date on the Gregorian calendar. MONTH and DAY are
+ numbers, STRING is the name of the holiday.
+
+`(holiday-float MONTH DAYNAME K STRING)'
+ The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for
+ Sunday, and so on); negative K means count back from the end of
+ the month. STRING is the name of the holiday.
+
+`(holiday-hebrew MONTH DAY STRING)'
+ A fixed date on the Hebrew calendar. MONTH and DAY are numbers,
+ STRING is the name of the holiday.
+
+`(holiday-islamic MONTH DAY STRING)'
+ A fixed date on the Islamic calendar. MONTH and DAY are numbers,
+ STRING is the name of the holiday.
+
+`(holiday-julian MONTH DAY STRING)'
+ A fixed date on the Julian calendar. MONTH and DAY are numbers,
+ STRING is the name of the holiday.
+
+`(holiday-sexp SEXP STRING)'
+ A date calculated by the Lisp expression SEXP. The expression
+ should use the variable `year' to compute and return the date of a
+ holiday, or `nil' if the holiday doesn't happen this year. The
+ value of SEXP must represent the date as a list of the form
+ `(MONTH DAY YEAR)'. STRING is the name of the holiday.
+
+`(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)'
+ A holiday that happens only if CONDITION is true.
+
+`(FUNCTION [ARGS])'
+ A list of dates calculated by the function FUNCTION, called with
+ arguments ARGS.
+
+ For example, suppose you want to add Bastille Day, celebrated in
+France on July 14. You can do this by adding the following line to
+your `.emacs' file:
+
+ (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
+
+The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the
+fourteenth day of the seventh month (July).
+
+ Many holidays occur on a specific day of the week, at a specific time
+of month. Here is a holiday form describing Hurricane Supplication Day,
+celebrated in the Virgin Islands on the fourth Monday in August:
+
+ (holiday-float 8 1 4 "Hurricane Supplication Day")
+
+Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
+Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
+the month (1 specifies the first occurrence, 2 the second occurrence,
+-1 the last occurrence, -2 the second-to-last occurrence, and so on).
+
+ You can specify holidays that occur on fixed days of the Hebrew,
+Islamic, and Julian calendars too. For example,
+
+ (setq other-holidays
+ '((holiday-hebrew 10 2 "Last day of Hanukkah")
+ (holiday-islamic 3 12 "Mohammed's Birthday")
+ (holiday-julian 4 2 "Jefferson's Birthday")))
+
+adds the last day of Hanukkah (since the Hebrew months are numbered with
+1 starting from Nisan), the Islamic feast celebrating Mohammed's
+birthday (since the Islamic months are numbered from 1 starting with
+Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
+Julian calendar.
+
+ To include a holiday conditionally, use either Emacs Lisp's `if' or
+the `holiday-sexp' form. For example, American presidential elections
+occur on the first Tuesday after the first Monday in November of years
+divisible by 4:
+
+ (holiday-sexp (if (= 0 (% year 4))
+ (calendar-gregorian-from-absolute
+ (1+ (calendar-dayname-on-or-before
+ 1 (+ 6 (calendar-absolute-from-gregorian
+ (list 11 1 year))))))
+ "US Presidential Election"))
+
+or
+
+ (if (= 0 (% displayed-year 4))
+ (fixed 11
+ (extract-calendar-day
+ (calendar-gregorian-from-absolute
+ (1+ (calendar-dayname-on-or-before
+ 1 (+ 6 (calendar-absolute-from-gregorian
+ (list 11 1 displayed-year)))))))
+ "US Presidential Election"))
+
+ Some holidays just don't fit into any of these forms because special
+calculations are involved in their determination. In such cases you
+must write a Lisp function to do the calculation. To include eclipses,
+for example, add `(eclipses)' to `other-holidays' and write an Emacs
+Lisp function `eclipses' that returns a (possibly empty) list of the
+relevant Gregorian dates among the range visible in the calendar
+window, with descriptive strings, like this:
+
+ (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
+
+\1f
+File: xemacs.info, Node: Date Display Format, Next: Time Display Format, Prev: Holiday Customizing, Up: Calendar Customization
+
+Date Display Format
+...................
+
+ You can customize the manner of displaying dates in the diary, in
+mode lines, and in messages by setting `calendar-date-display-form'.
+This variable holds a list of expressions that can involve the variables
+`month', `day', and `year', which are all numbers in string form, and
+`monthname' and `dayname', which are both alphabetic strings. In the
+American style, the default value of this list is as follows:
+
+ ((if dayname (concat dayname ", ")) monthname " " day ", " year)
+
+while in the European style this value is the default:
+
+ ((if dayname (concat dayname ", ")) day " " monthname " " year)
+
+ + The ISO standard date representation is this:
+
+ (year "-" month "-" day)
+
+This specifies a typical American format:
+
+ (month "/" day "/" (substring year -2))
+
+\1f
+File: xemacs.info, Node: Time Display Format, Next: Daylight Savings, Prev: Date Display Format, Up: Calendar Customization
+
+Time Display Format
+...................
+
+ The calendar and diary by default display times of day in the
+conventional American style with the hours from 1 through 12, minutes,
+and either `am' or `pm'. If you prefer the European style, also known
+in the US as military, in which the hours go from 00 to 23, you can
+alter the variable `calendar-time-display-form'. This variable is a
+list of expressions that can involve the variables `12-hours',
+`24-hours', and `minutes', which are all numbers in string form, and
+`am-pm' and `time-zone', which are both alphabetic strings. The
+default value of `calendar-time-display-form' is as follows:
+
+ (12-hours ":" minutes am-pm
+ (if time-zone " (") time-zone (if time-zone ")"))
+
+Here is a value that provides European style times:
+
+ (24-hours ":" minutes
+ (if time-zone " (") time-zone (if time-zone ")"))
+
+gives military-style times like `21:07 (UT)' if time zone names are
+defined, and times like `21:07' if they are not.
+
+\1f
+File: xemacs.info, Node: Daylight Savings, Next: Diary Customizing, Prev: Time Display Format, Up: Calendar Customization
+
+Daylight Savings Time
+.....................
+
+ Emacs understands the difference between standard time and daylight
+savings time--the times given for sunrise, sunset, solstices,
+equinoxes, and the phases of the moon take that into account. The rules
+for daylight savings time vary from place to place and have also varied
+historically from year to year. To do the job properly, Emacs needs to
+know which rules to use.
+
+ Some operating systems keep track of the rules that apply to the
+place where you are; on these systems, Emacs gets the information it
+needs from the system automatically. If some or all of this
+information is missing, Emacs fills in the gaps with the rules
+currently used in Cambridge, Massachusetts. If the resulting rules are
+not what you want, you can tell Emacs the rules to use by setting
+certain variables.
+
+ If the default choice of rules is not appropriate for your location,
+you can tell Emacs the rules to use by setting the variables
+`calendar-daylight-savings-starts' and
+`calendar-daylight-savings-ends'. Their values should be Lisp
+expressions that refer to the variable `year', and evaluate to the
+Gregorian date on which daylight savings time starts or (respectively)
+ends, in the form of a list `(MONTH DAY YEAR)'. The values should be
+`nil' if your area does not use daylight savings time.
+
+ Emacs uses these expressions to determine the starting date of
+daylight savings time for the holiday list and for correcting times of
+day in the solar and lunar calculations.
+
+ The values for Cambridge, Massachusetts are as follows:
+
+ (calendar-nth-named-day 1 0 4 year)
+ (calendar-nth-named-day -1 0 10 year)
+
+That is, the first 0th day (Sunday) of the fourth month (April) in the
+year specified by `year', and the last Sunday of the tenth month
+(October) of that year. If daylight savings time were changed to start
+on October 1, you would set `calendar-daylight-savings-starts' to this:
+
+ (list 10 1 year)
+
+ For a more complex example, suppose daylight savings time begins on
+the first of Nisan on the Hebrew calendar. You should set
+`calendar-daylight-savings-starts' to this value:
+
+ (calendar-gregorian-from-absolute
+ (calendar-absolute-from-hebrew
+ (list 1 1 (+ year 3760))))
+
+because Nisan is the first month in the Hebrew calendar and the Hebrew
+year differs from the Gregorian year by 3760 at Nisan.
+
+ If there is no daylight savings time at your location, or if you want
+all times in standard time, set `calendar-daylight-savings-starts' and
+`calendar-daylight-savings-ends' to `nil'.
+
+ The variable `calendar-daylight-time-offset' specifies the
+difference between daylight savings time and standard time, measured in
+minutes. The value for Cambridge, Massachusetts is 60.
+
+ The two variables `calendar-daylight-savings-starts-time' and
+`calendar-daylight-savings-ends-time' specify the number of minutes
+after midnight local time when the transition to and from daylight
+savings time should occur. For Cambridge, Massachusetts both variables'
+values are 120.
+
+\1f
File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization
Customizing the Diary
a list of strings, each string a switch starting with `-'. For
example, the value could be `("-Pfoo")' to print on printer `foo'.
-\1f
-File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top
-
-Recursive Editing Levels
-========================
-
- A "recursive edit" is a situation in which you are using XEmacs
-commands to perform arbitrary editing while in the middle of another
-XEmacs command. For example, when you type `C-r' inside a
-`query-replace', you enter a recursive edit in which you can change the
-current buffer. When you exit from the recursive edit, you go back to
-the `query-replace'.
-
- "Exiting" a recursive edit means returning to the unfinished
-command, which continues execution. For example, exiting the recursive
-edit requested by `C-r' in `query-replace' causes query replacing to
-resume. Exiting is done with `C-M-c' (`exit-recursive-edit').
-
- You can also "abort" a recursive edit. This is like exiting, but
-also quits the unfinished command immediately. Use the command `C-]'
-(`abort-recursive-edit') for this. *Note Quitting::.
-
- The mode line shows you when you are in a recursive edit by
-displaying square brackets around the parentheses that always surround
-the major and minor mode names. Every window's mode line shows the
-square brackets, since XEmacs as a whole, rather than any particular
-buffer, is in a recursive edit.
-
- It is possible to be in recursive edits within recursive edits. For
-example, after typing `C-r' in a `query-replace', you might type a
-command that entered the debugger. In such a case, two or more sets of
-square brackets appear in the mode line(s). Exiting the inner
-recursive edit (here with the debugger `c' command) resumes the
-query-replace command where it called the debugger. After the end of
-the query-replace command, you would be able to exit the first
-recursive edit. Aborting exits only one level of recursive edit; it
-returns to the command level of the previous recursive edit. You can
-then abort that one as well.
-
- The command `M-x top-level' aborts all levels of recursive edits,
-returning immediately to the top level command reader.
-
- The text you edit inside the recursive edit need not be the same text
-that you were editing at top level. If the command that invokes the
-recursive edit selects a different buffer first, that is the buffer you
-will edit recursively. You can switch buffers within the recursive edit
-in the normal manner (as long as the buffer-switching keys have not been
-rebound). While you could theoretically do the rest of your editing
-inside the recursive edit, including visiting files, this could have
-surprising effects (such as stack overflow) from time to time. It is
-best if you always exit or abort a recursive edit when you no longer
-need it.
-
- In general, XEmacs tries to avoid using recursive edits. It is
-usually preferable to allow users to switch among the possible editing
-modes in any order they like. With recursive edits, the only way to get
-to another state is to go "back" to the state that the recursive edit
-was invoked from.
-
-\1f
-File: xemacs.info, Node: Dissociated Press, Next: CONX, Prev: Recursive Edit, Up: Top
-
-Dissociated Press
-=================
-
- `M-x dissociated-press' is a command for scrambling a file of text
-either word by word or character by character. Starting from a buffer
-of straight English, it produces extremely amusing output. The input
-comes from the current XEmacs buffer. Dissociated Press writes its
-output in a buffer named `*Dissociation*', and redisplays that buffer
-after every couple of lines (approximately) to facilitate reading it.
-
- `dissociated-press' asks every so often whether to continue
-operating. Answer `n' to stop it. You can also stop at any time by
-typing `C-g'. The dissociation output remains in the `*Dissociation*'
-buffer for you to copy elsewhere if you wish.
-
- Dissociated Press operates by jumping at random from one point in the
-buffer to another. In order to produce plausible output rather than
-gibberish, it insists on a certain amount of overlap between the end of
-one run of consecutive words or characters and the start of the next.
-That is, if it has just printed out `president' and then decides to
-jump to a different point in the file, it might spot the `ent' in
-`pentagon' and continue from there, producing `presidentagon'. Long
-sample texts produce the best results.
-
- A positive argument to `M-x dissociated-press' tells it to operate
-character by character, and specifies the number of overlap characters.
-A negative argument tells it to operate word by word and specifies the
-number of overlap words. In this mode, whole words are treated as the
-elements to be permuted, rather than characters. No argument is
-equivalent to an argument of two. For your againformation, the output
-goes only into the buffer `*Dissociation*'. The buffer you start with
-is not changed.
-
- Dissociated Press produces nearly the same results as a Markov chain
-based on a frequency table constructed from the sample text. It is,
-however, an independent, ignoriginal invention. Dissociated Press
-techniquitously copies several consecutive characters from the sample
-between random choices, whereas a Markov chain would choose randomly for
-each word or character. This makes for more plausible sounding results
-and runs faster.
-
- It is a mustatement that too much use of Dissociated Press can be a
-developediment to your real work. Sometimes to the point of outragedy.
-And keep dissociwords out of your documentation, if you want it to be
-well userenced and properbose. Have fun. Your buggestions are welcome.
-
-\1f
-File: xemacs.info, Node: CONX, Next: Amusements, Prev: Dissociated Press, Up: Top
-
-CONX
-====
-
- Besides producing a file of scrambled text with Dissociated Press,
-you can generate random sentences by using CONX.
-
-`M-x conx'
- Generate random sentences in the `*conx*' buffer.
-
-`M-x conx-buffer'
- Absorb the text in the current buffer into the `conx' database.
-
-`M-x conx-init'
- Forget the current word-frequency tree.
-
-`M-x conx-load'
- Load a `conx' database that has been previously saved with `M-x
- conx-save'.
-
-`M-x conx-region'
- Absorb the text in the current buffer into the `conx' database.
-
-`M-x conx-save'
- Save the current `conx' database to a file for future retrieval.
-
- Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region'
-and then type `M-x conx'. Output is continuously generated until you
-type <^G>. You can save the `conx' database to a file with `M-x
-conx-save', which you can retrieve with `M-x conx-load'. To clear the
-database, use `M-x conx-init'.
-
-\1f
-File: xemacs.info, Node: Amusements, Next: Emulation, Prev: CONX, Up: Top
-
-Other Amusements
-================
-
- If you are a little bit bored, you can try `M-x hanoi'. If you are
-considerably bored, give it a numeric argument. If you are very, very
-bored, try an argument of 9. Sit back and watch.
-
- When you are frustrated, try the famous Eliza program. Just do `M-x
-doctor'. End each input by typing `RET' twice.
-
- When you are feeling strange, type `M-x yow'.
-
-\1f
-File: xemacs.info, Node: Emulation, Next: Customization, Prev: Amusements, Up: Top
-
-Emulation
-=========
-
- XEmacs can be programmed to emulate (more or less) most other
-editors. Standard facilities can emulate these:
-
-Viper (a vi emulator)
- In XEmacs, Viper is the preferred emulation of vi within XEmacs.
- Viper is designed to allow you to take advantage of the best
- features of XEmacs while still doing your basic editing in a
- familiar, vi-like fashion. Viper provides various different
- levels of vi emulation, from a quite complete emulation that
- allows almost no access to native XEmacs commands, to an "expert"
- mode that combines the most useful vi commands with the most
- useful XEmacs commands.
-
- To start Viper, put the command
-
- (viper-mode)
-
- in your `.emacs' file.
-
- Viper comes with a separate manual that is provided standard with
- the XEmacs distribution.
-
-EDT (DEC VMS editor)
- Turn on EDT emulation with `M-x edt-emulation-on'. `M-x
- edt-emulation-off' restores normal Emacs command bindings.
-
- Most of the EDT emulation commands are keypad keys, and most
- standard Emacs key bindings are still available. The EDT
- emulation rebindings are done in the global keymap, so there is no
- problem switching buffers or major modes while in EDT emulation.
-
-Gosling Emacs
- Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x
- set-gosmacs-bindings'. This redefines many keys, mostly on the
- `C-x' and `ESC' prefixes, to work as they do in Gosmacs. `M-x
- set-gnu-bindings' returns to normal XEmacs by rebinding the same
- keys to the definitions they had at the time `M-x
- set-gosmacs-bindings' was done.
-
- It is also possible to run Mocklisp code written for Gosling Emacs.
- *Note Mocklisp::.
-
-\1f
-File: xemacs.info, Node: Customization, Next: Quitting, Prev: Emulation, Up: Top
-
-Customization
-*************
-
- This chapter talks about various topics relevant to adapting the
-behavior of Emacs in minor ways.
-
- All kinds of customization affect only the particular Emacs job that
-you do them in. They are completely lost when you kill the Emacs job,
-and have no effect on other Emacs jobs you may run at the same time or
-later. The only way an Emacs job can affect anything outside of it is
-by writing a file; in particular, the only way to make a customization
-`permanent' is to put something in your `.emacs' file or other
-appropriate file to do the customization in each session. *Note Init
-File::.
-
-* Menu:
-
-* Minor Modes:: Each minor mode is one feature you can turn on
- independently of any others.
-* Variables:: Many Emacs commands examine Emacs variables
- to decide what to do; by setting variables,
- you can control their functioning.
-* Keyboard Macros:: A keyboard macro records a sequence of keystrokes
- to be replayed with a single command.
-* Key Bindings:: The keymaps say what command each key runs.
- By changing them, you can "redefine keys".
-* Syntax:: The syntax table controls how words and expressions
- are parsed.
-* Init File:: How to write common customizations in the `.emacs'
- file.
-* Audible Bell:: Changing how Emacs sounds the bell.
-* Faces:: Changing the fonts and colors of a region of text.
-* X Resources:: X resources controlling various aspects of the
- behavior of XEmacs.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top
+
+Recursive Editing Levels
+========================
+
+ A "recursive edit" is a situation in which you are using XEmacs
+commands to perform arbitrary editing while in the middle of another
+XEmacs command. For example, when you type `C-r' inside a
+`query-replace', you enter a recursive edit in which you can change the
+current buffer. When you exit from the recursive edit, you go back to
+the `query-replace'.
+
+ "Exiting" a recursive edit means returning to the unfinished
+command, which continues execution. For example, exiting the recursive
+edit requested by `C-r' in `query-replace' causes query replacing to
+resume. Exiting is done with `C-M-c' (`exit-recursive-edit').
+
+ You can also "abort" a recursive edit. This is like exiting, but
+also quits the unfinished command immediately. Use the command `C-]'
+(`abort-recursive-edit') for this. *Note Quitting::.
+
+ The mode line shows you when you are in a recursive edit by
+displaying square brackets around the parentheses that always surround
+the major and minor mode names. Every window's mode line shows the
+square brackets, since XEmacs as a whole, rather than any particular
+buffer, is in a recursive edit.
+
+ It is possible to be in recursive edits within recursive edits. For
+example, after typing `C-r' in a `query-replace', you might type a
+command that entered the debugger. In such a case, two or more sets of
+square brackets appear in the mode line(s). Exiting the inner
+recursive edit (here with the debugger `c' command) resumes the
+query-replace command where it called the debugger. After the end of
+the query-replace command, you would be able to exit the first
+recursive edit. Aborting exits only one level of recursive edit; it
+returns to the command level of the previous recursive edit. You can
+then abort that one as well.
+
+ The command `M-x top-level' aborts all levels of recursive edits,
+returning immediately to the top level command reader.
+
+ The text you edit inside the recursive edit need not be the same text
+that you were editing at top level. If the command that invokes the
+recursive edit selects a different buffer first, that is the buffer you
+will edit recursively. You can switch buffers within the recursive edit
+in the normal manner (as long as the buffer-switching keys have not been
+rebound). While you could theoretically do the rest of your editing
+inside the recursive edit, including visiting files, this could have
+surprising effects (such as stack overflow) from time to time. It is
+best if you always exit or abort a recursive edit when you no longer
+need it.
+
+ In general, XEmacs tries to avoid using recursive edits. It is
+usually preferable to allow users to switch among the possible editing
+modes in any order they like. With recursive edits, the only way to get
+to another state is to go "back" to the state that the recursive edit
+was invoked from.
+
+\1f
+File: xemacs.info, Node: Dissociated Press, Next: CONX, Prev: Recursive Edit, Up: Top
+
+Dissociated Press
+=================
+
+ `M-x dissociated-press' is a command for scrambling a file of text
+either word by word or character by character. Starting from a buffer
+of straight English, it produces extremely amusing output. The input
+comes from the current XEmacs buffer. Dissociated Press writes its
+output in a buffer named `*Dissociation*', and redisplays that buffer
+after every couple of lines (approximately) to facilitate reading it.
+
+ `dissociated-press' asks every so often whether to continue
+operating. Answer `n' to stop it. You can also stop at any time by
+typing `C-g'. The dissociation output remains in the `*Dissociation*'
+buffer for you to copy elsewhere if you wish.
+
+ Dissociated Press operates by jumping at random from one point in the
+buffer to another. In order to produce plausible output rather than
+gibberish, it insists on a certain amount of overlap between the end of
+one run of consecutive words or characters and the start of the next.
+That is, if it has just printed out `president' and then decides to
+jump to a different point in the file, it might spot the `ent' in
+`pentagon' and continue from there, producing `presidentagon'. Long
+sample texts produce the best results.
+
+ A positive argument to `M-x dissociated-press' tells it to operate
+character by character, and specifies the number of overlap characters.
+A negative argument tells it to operate word by word and specifies the
+number of overlap words. In this mode, whole words are treated as the
+elements to be permuted, rather than characters. No argument is
+equivalent to an argument of two. For your againformation, the output
+goes only into the buffer `*Dissociation*'. The buffer you start with
+is not changed.
+
+ Dissociated Press produces nearly the same results as a Markov chain
+based on a frequency table constructed from the sample text. It is,
+however, an independent, ignoriginal invention. Dissociated Press
+techniquitously copies several consecutive characters from the sample
+between random choices, whereas a Markov chain would choose randomly for
+each word or character. This makes for more plausible sounding results
+and runs faster.
+
+ It is a mustatement that too much use of Dissociated Press can be a
+developediment to your real work. Sometimes to the point of outragedy.
+And keep dissociwords out of your documentation, if you want it to be
+well userenced and properbose. Have fun. Your buggestions are welcome.
+
+\1f
+File: xemacs.info, Node: CONX, Next: Amusements, Prev: Dissociated Press, Up: Top
+
+CONX
+====
+
+ Besides producing a file of scrambled text with Dissociated Press,
+you can generate random sentences by using CONX.
+
+`M-x conx'
+ Generate random sentences in the `*conx*' buffer.
+
+`M-x conx-buffer'
+ Absorb the text in the current buffer into the `conx' database.
+
+`M-x conx-init'
+ Forget the current word-frequency tree.
+
+`M-x conx-load'
+ Load a `conx' database that has been previously saved with `M-x
+ conx-save'.
+
+`M-x conx-region'
+ Absorb the text in the current buffer into the `conx' database.
+
+`M-x conx-save'
+ Save the current `conx' database to a file for future retrieval.
+
+ Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region'
+and then type `M-x conx'. Output is continuously generated until you
+type <^G>. You can save the `conx' database to a file with `M-x
+conx-save', which you can retrieve with `M-x conx-load'. To clear the
+database, use `M-x conx-init'.
+
+\1f
+File: xemacs.info, Node: Amusements, Next: Emulation, Prev: CONX, Up: Top
+
+Other Amusements
+================
+
+ If you are a little bit bored, you can try `M-x hanoi'. If you are
+considerably bored, give it a numeric argument. If you are very, very
+bored, try an argument of 9. Sit back and watch.
+
+ When you are frustrated, try the famous Eliza program. Just do `M-x
+doctor'. End each input by typing `RET' twice.
+
+ When you are feeling strange, type `M-x yow'.
+
+\1f
+File: xemacs.info, Node: Emulation, Next: Customization, Prev: Amusements, Up: Top
+
+Emulation
+=========
+
+ XEmacs can be programmed to emulate (more or less) most other
+editors. Standard facilities can emulate these:
+
+Viper (a vi emulator)
+ In XEmacs, Viper is the preferred emulation of vi within XEmacs.
+ Viper is designed to allow you to take advantage of the best
+ features of XEmacs while still doing your basic editing in a
+ familiar, vi-like fashion. Viper provides various different
+ levels of vi emulation, from a quite complete emulation that
+ allows almost no access to native XEmacs commands, to an "expert"
+ mode that combines the most useful vi commands with the most
+ useful XEmacs commands.
+
+ To start Viper, put the command
+
+ (viper-mode)
+
+ in your `.emacs' file.
+
+ Viper comes with a separate manual that is provided standard with
+ the XEmacs distribution.
+
+EDT (DEC VMS editor)
+ Turn on EDT emulation with `M-x edt-emulation-on'. `M-x
+ edt-emulation-off' restores normal Emacs command bindings.
+
+ Most of the EDT emulation commands are keypad keys, and most
+ standard Emacs key bindings are still available. The EDT
+ emulation rebindings are done in the global keymap, so there is no
+ problem switching buffers or major modes while in EDT emulation.
+
+Gosling Emacs
+ Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x
+ set-gosmacs-bindings'. This redefines many keys, mostly on the
+ `C-x' and `ESC' prefixes, to work as they do in Gosmacs. `M-x
+ set-gnu-bindings' returns to normal XEmacs by rebinding the same
+ keys to the definitions they had at the time `M-x
+ set-gosmacs-bindings' was done.
+
+ It is also possible to run Mocklisp code written for Gosling Emacs.
+ *Note Mocklisp::.
+
+\1f
+File: xemacs.info, Node: Customization, Next: Quitting, Prev: Emulation, Up: Top
+
+Customization
+*************
+
+ This chapter talks about various topics relevant to adapting the
+behavior of Emacs in minor ways.
+
+ All kinds of customization affect only the particular Emacs job that
+you do them in. They are completely lost when you kill the Emacs job,
+and have no effect on other Emacs jobs you may run at the same time or
+later. The only way an Emacs job can affect anything outside of it is
+by writing a file; in particular, the only way to make a customization
+`permanent' is to put something in your `.emacs' file or other
+appropriate file to do the customization in each session. *Note Init
+File::.
+
+* Menu:
+
+* Minor Modes:: Each minor mode is one feature you can turn on
+ independently of any others.
+* Variables:: Many Emacs commands examine Emacs variables
+ to decide what to do; by setting variables,
+ you can control their functioning.
+* Keyboard Macros:: A keyboard macro records a sequence of keystrokes
+ to be replayed with a single command.
+* Key Bindings:: The keymaps say what command each key runs.
+ By changing them, you can "redefine keys".
+* Syntax:: The syntax table controls how words and expressions
+ are parsed.
+* Init File:: How to write common customizations in the `.emacs'
+ file.
+* Audible Bell:: Changing how Emacs sounds the bell.
+* Faces:: Changing the fonts and colors of a region of text.
+* Frame Components:: Controlling the presence and positions of the
+ menubar, toolbars, and gutters.
+* X Resources:: X resources controlling various aspects of the
+ behavior of XEmacs.
+
+\1f
File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization
Minor Modes
before it can be executed. This is done to protect
beginners from surprises.
-\1f
-File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
-
-Keymaps
--------
-
- The bindings between characters and command functions are recorded in
-data structures called "keymaps". Emacs has many of these. One, the
-"global" keymap, defines the meanings of the single-character keys that
-are defined regardless of major mode. It is the value of the variable
-`global-map'.
-
- Each major mode has another keymap, its "local keymap", which
-contains overriding definitions for the single-character keys that are
-redefined in that mode. Each buffer records which local keymap is
-installed for it at any time, and the current buffer's local keymap is
-the only one that directly affects command execution. The local keymaps
-for Lisp mode, C mode, and many other major modes always exist even when
-not in use. They are the values of the variables `lisp-mode-map',
-`c-mode-map', and so on. For less frequently used major modes, the
-local keymap is sometimes constructed only when the mode is used for the
-first time in a session, to save space.
-
- There are local keymaps for the minibuffer, too; they contain various
-completion and exit commands.
-
- * `minibuffer-local-map' is used for ordinary input (no completion).
-
- * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
- like <RET>. This is used mainly for Mocklisp compatibility.
-
- * `minibuffer-local-completion-map' is for permissive completion.
-
- * `minibuffer-local-must-match-map' is for strict completion and for
- cautious completion.
-
- * `repeat-complex-command-map' is for use in `C-x <ESC>'.
-
- * `isearch-mode-map' contains the bindings of the special keys which
- are bound in the pseudo-mode entered with `C-s' and `C-r'.
-
- Finally, each prefix key has a keymap which defines the key sequences
-that start with it. For example, `ctl-x-map' is the keymap used for
-characters following a `C-x'.
-
- * `ctl-x-map' is the variable name for the map used for characters
- that follow `C-x'.
-
- * `help-map' is used for characters that follow `C-h'.
-
- * `esc-map' is for characters that follow <ESC>. All Meta characters
- are actually defined by this map.
-
- * `ctl-x-4-map' is for characters that follow `C-x 4'.
-
- * `mode-specific-map' is for characters that follow `C-c'.
-
- The definition of a prefix key is the keymap to use for looking up
-the following character. Sometimes the definition is actually a Lisp
-symbol whose function definition is the following character keymap. The
-effect is the same, but it provides a command name for the prefix key
-that you can use as a description of what the prefix key is for. Thus
-the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
-definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
-
- Prefix key definitions can appear in either the global map or a
-local map. The definitions of `C-c', `C-x', `C-h', and <ESC> as prefix
-keys appear in the global map, so these prefix keys are always
-available. Major modes can locally redefine a key as a prefix by
-putting a prefix key definition for it in the local map.
-
- A mode can also put a prefix definition of a global prefix character
-such as `C-x' into its local map. This is how major modes override the
-definitions of certain keys that start with `C-x'. This case is
-special, because the local definition does not entirely replace the
-global one. When both the global and local definitions of a key are
-other keymaps, the next character is looked up in both keymaps, with
-the local definition overriding the global one. The character after the
-`C-x' is looked up in both the major mode's own keymap for redefined
-`C-x' commands and in `ctl-x-map'. If the major mode's own keymap for
-`C-x' commands contains `nil', the definition from the global keymap
-for `C-x' commands is used.
-
-\1f
-File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings
-
-Changing Key Bindings
----------------------
-
- You can redefine an Emacs key by changing its entry in a keymap.
-You can change the global keymap, in which case the change is effective
-in all major modes except those that have their own overriding local
-definitions for the same key. Or you can change the current buffer's
-local map, which affects all buffers using the same major mode.
-
-* Menu:
-
-* Interactive Rebinding:: Changing Key Bindings Interactively
-* Programmatic Rebinding:: Changing Key Bindings Programmatically
-* Key Bindings Using Strings:: Using Strings for Changing Key Bindings
-
-\1f
-File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding
-
-Changing Key Bindings Interactively
-...................................
-
-`M-x global-set-key <RET> KEY CMD <RET>'
- Defines KEY globally to run CMD.
-
-`M-x local-set-key <RET> KEYS CMD <RET>'
- Defines KEY locally (in the major mode now in effect) to run CMD.
-
-`M-x local-unset-key <RET> KEYS <RET>'
- Removes the local binding of KEY.
-
- CMD is a symbol naming an interactively-callable function.
-
- When called interactively, KEY is the next complete key sequence
-that you type. When called as a function, KEY is a string, a vector of
-events, or a vector of key-description lists as described in the
-`define-key' function description. The binding goes in the current
-buffer's local map, which is shared with other buffers in the same
-major mode.
-
- The following example:
-
- M-x global-set-key <RET> C-f next-line <RET>
-
-redefines `C-f' to move down a line. The fact that CMD is read second
-makes it serve as a kind of confirmation for KEY.
-
- These functions offer no way to specify a particular prefix keymap as
-the one to redefine in, but that is not necessary, as you can include
-prefixes in KEY. KEY is read by reading characters one by one until
-they amount to a complete key (that is, not a prefix key). Thus, if
-you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
-CMD. But if you type `C-x', another character is read; if that
-character is `4', another character is read, and so on. For example,
-
- M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
-
-redefines `C-x 4 $' to run the (fictitious) command
-`spell-other-window'.
-
- The most general way to modify a keymap is the function
-`define-key', used in Lisp code (such as your `.emacs' file).
-`define-key' takes three arguments: the keymap, the key to modify in
-it, and the new definition. *Note Init File::, for an example.
-`substitute-key-definition' is used similarly; it takes three
-arguments, an old definition, a new definition, and a keymap, and
-redefines in that keymap all keys that were previously defined with the
-old definition to have the new definition instead.
-
-\1f
-File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding
-
-Changing Key Bindings Programmatically
-......................................
-
- You can use the functions `global-set-key' and `define-key' to
-rebind keys under program control.
-
-``(global-set-key KEYS CMD)''
- Defines KEYS globally to run CMD.
-
-``(define-key KEYMAP KEYS DEF)''
- Defines KEYS to run DEF in the keymap KEYMAP.
-
- KEYMAP is a keymap object.
-
- KEYS is the sequence of keystrokes to bind.
-
- DEF is anything that can be a key's definition:
-
- * `nil', meaning key is undefined in this keymap
-
- * A command, that is, a Lisp function suitable for interactive
- calling
-
- * A string or key sequence vector, which is treated as a keyboard
- macro
-
- * A keymap to define a prefix key
-
- * A symbol so that when the key is looked up, the symbol stands for
- its function definition, which should at that time be one of the
- above, or another symbol whose function definition is used, and so
- on
-
- * A cons, `(string . defn)', meaning that DEFN is the definition
- (DEFN should be a valid definition in its own right)
-
- * A cons, `(keymap . char)', meaning use the definition of CHAR in
- map KEYMAP
-
- For backward compatibility, XEmacs allows you to specify key
-sequences as strings. However, the preferred method is to use the
-representations of key sequences as vectors of keystrokes. *Note
-Keystrokes::, for more information about the rules for constructing key
-sequences.
-
- Emacs allows you to abbreviate representations for key sequences in
-most places where there is no ambiguity. Here are some rules for
-abbreviation:
-
- * The keysym by itself is equivalent to a list of just that keysym,
- i.e., `f1' is equivalent to `(f1)'.
-
- * A keystroke by itself is equivalent to a vector containing just
- that keystroke, i.e., `(control a)' is equivalent to `[(control
- a)]'.
-
- * You can use ASCII codes for keysyms that have them. i.e., `65' is
- equivalent to `A'. (This is not so much an abbreviation as an
- alternate representation.)
-
- Here are some examples of programmatically binding keys:
-
-
- ;;; Bind `my-command' to <f1>
- (global-set-key 'f1 'my-command)
-
- ;;; Bind `my-command' to Shift-f1
- (global-set-key '(shift f1) 'my-command)
-
- ;;; Bind `my-command' to C-c Shift-f1
- (global-set-key '[(control c) (shift f1)] 'my-command)
-
- ;;; Bind `my-command' to the middle mouse button.
- (global-set-key 'button2 'my-command)
-
- ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
- ;;; in the keymap that is in force when you are running `dired'.
- (define-key dired-mode-map '(meta control button3) 'my-command)
-
-\1f
-File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding
-
-Using Strings for Changing Key Bindings
-.......................................
-
- For backward compatibility, you can still use strings to represent
-key sequences. Thus you can use commands like the following:
-
- ;;; Bind `end-of-line' to C-f
- (global-set-key "\C-f" 'end-of-line)
-
- Note, however, that in some cases you may be binding more than one
-key sequence by using a single command. This situation can arise
-because in ASCII, `C-i' and <TAB> have the same representation.
-Therefore, when Emacs sees:
-
- (global-set-key "\C-i" 'end-of-line)
-
- it is unclear whether the user intended to bind `C-i' or <TAB>. The
-solution XEmacs adopts is to bind both of these key sequences.
-
- After binding a command to two key sequences with a form like:
-
- (define-key global-map "\^X\^I" 'command-1)
-
- it is possible to redefine only one of those sequences like so:
-
- (define-key global-map [(control x) (control i)] 'command-2)
- (define-key global-map [(control x) tab] 'command-3)
-
- This applies only when running under a window system. If you are
-talking to Emacs through an ASCII-only channel, you do not get any of
-these features.
-
- Here is a table of pairs of key sequences that behave in a similar
-fashion:
-
- control h backspace
- control l clear
- control i tab
- control m return
- control j linefeed
- control [ escape
- control @ control space
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
+
+Keymaps
+-------
+
+ The bindings between characters and command functions are recorded in
+data structures called "keymaps". Emacs has many of these. One, the
+"global" keymap, defines the meanings of the single-character keys that
+are defined regardless of major mode. It is the value of the variable
+`global-map'.
+
+ Each major mode has another keymap, its "local keymap", which
+contains overriding definitions for the single-character keys that are
+redefined in that mode. Each buffer records which local keymap is
+installed for it at any time, and the current buffer's local keymap is
+the only one that directly affects command execution. The local keymaps
+for Lisp mode, C mode, and many other major modes always exist even when
+not in use. They are the values of the variables `lisp-mode-map',
+`c-mode-map', and so on. For less frequently used major modes, the
+local keymap is sometimes constructed only when the mode is used for the
+first time in a session, to save space.
+
+ There are local keymaps for the minibuffer, too; they contain various
+completion and exit commands.
+
+ * `minibuffer-local-map' is used for ordinary input (no completion).
+
+ * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
+ like <RET>. This is used mainly for Mocklisp compatibility.
+
+ * `minibuffer-local-completion-map' is for permissive completion.
+
+ * `minibuffer-local-must-match-map' is for strict completion and for
+ cautious completion.
+
+ * `repeat-complex-command-map' is for use in `C-x <ESC>'.
+
+ * `isearch-mode-map' contains the bindings of the special keys which
+ are bound in the pseudo-mode entered with `C-s' and `C-r'.
+
+ Finally, each prefix key has a keymap which defines the key sequences
+that start with it. For example, `ctl-x-map' is the keymap used for
+characters following a `C-x'.
+
+ * `ctl-x-map' is the variable name for the map used for characters
+ that follow `C-x'.
+
+ * `help-map' is used for characters that follow `C-h'.
+
+ * `esc-map' is for characters that follow <ESC>. All Meta characters
+ are actually defined by this map.
+
+ * `ctl-x-4-map' is for characters that follow `C-x 4'.
+
+ * `mode-specific-map' is for characters that follow `C-c'.
+
+ The definition of a prefix key is the keymap to use for looking up
+the following character. Sometimes the definition is actually a Lisp
+symbol whose function definition is the following character keymap. The
+effect is the same, but it provides a command name for the prefix key
+that you can use as a description of what the prefix key is for. Thus
+the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
+definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
+
+ Prefix key definitions can appear in either the global map or a
+local map. The definitions of `C-c', `C-x', `C-h', and <ESC> as prefix
+keys appear in the global map, so these prefix keys are always
+available. Major modes can locally redefine a key as a prefix by
+putting a prefix key definition for it in the local map.
+
+ A mode can also put a prefix definition of a global prefix character
+such as `C-x' into its local map. This is how major modes override the
+definitions of certain keys that start with `C-x'. This case is
+special, because the local definition does not entirely replace the
+global one. When both the global and local definitions of a key are
+other keymaps, the next character is looked up in both keymaps, with
+the local definition overriding the global one. The character after the
+`C-x' is looked up in both the major mode's own keymap for redefined
+`C-x' commands and in `ctl-x-map'. If the major mode's own keymap for
+`C-x' commands contains `nil', the definition from the global keymap
+for `C-x' commands is used.
+
+\1f
+File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings
+
+Changing Key Bindings
+---------------------
+
+ You can redefine an Emacs key by changing its entry in a keymap.
+You can change the global keymap, in which case the change is effective
+in all major modes except those that have their own overriding local
+definitions for the same key. Or you can change the current buffer's
+local map, which affects all buffers using the same major mode.
+
+* Menu:
+
+* Interactive Rebinding:: Changing Key Bindings Interactively
+* Programmatic Rebinding:: Changing Key Bindings Programmatically
+* Key Bindings Using Strings:: Using Strings for Changing Key Bindings
+
+\1f
+File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding
+
+Changing Key Bindings Interactively
+...................................
+
+`M-x global-set-key <RET> KEY CMD <RET>'
+ Defines KEY globally to run CMD.
+
+`M-x local-set-key <RET> KEYS CMD <RET>'
+ Defines KEY locally (in the major mode now in effect) to run CMD.
+
+`M-x local-unset-key <RET> KEYS <RET>'
+ Removes the local binding of KEY.
+
+ CMD is a symbol naming an interactively-callable function.
+
+ When called interactively, KEY is the next complete key sequence
+that you type. When called as a function, KEY is a string, a vector of
+events, or a vector of key-description lists as described in the
+`define-key' function description. The binding goes in the current
+buffer's local map, which is shared with other buffers in the same
+major mode.
+
+ The following example:
+
+ M-x global-set-key <RET> C-f next-line <RET>
+
+redefines `C-f' to move down a line. The fact that CMD is read second
+makes it serve as a kind of confirmation for KEY.
+
+ These functions offer no way to specify a particular prefix keymap as
+the one to redefine in, but that is not necessary, as you can include
+prefixes in KEY. KEY is read by reading characters one by one until
+they amount to a complete key (that is, not a prefix key). Thus, if
+you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
+CMD. But if you type `C-x', another character is read; if that
+character is `4', another character is read, and so on. For example,
+
+ M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
+
+redefines `C-x 4 $' to run the (fictitious) command
+`spell-other-window'.
+
+ The most general way to modify a keymap is the function
+`define-key', used in Lisp code (such as your `.emacs' file).
+`define-key' takes three arguments: the keymap, the key to modify in
+it, and the new definition. *Note Init File::, for an example.
+`substitute-key-definition' is used similarly; it takes three
+arguments, an old definition, a new definition, and a keymap, and
+redefines in that keymap all keys that were previously defined with the
+old definition to have the new definition instead.
+
+\1f
+File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding
+
+Changing Key Bindings Programmatically
+......................................
+
+ You can use the functions `global-set-key' and `define-key' to
+rebind keys under program control.
+
+``(global-set-key KEYS CMD)''
+ Defines KEYS globally to run CMD.
+
+``(define-key KEYMAP KEYS DEF)''
+ Defines KEYS to run DEF in the keymap KEYMAP.
+
+ KEYMAP is a keymap object.
+
+ KEYS is the sequence of keystrokes to bind.
+
+ DEF is anything that can be a key's definition:
+
+ * `nil', meaning key is undefined in this keymap
+
+ * A command, that is, a Lisp function suitable for interactive
+ calling
+
+ * A string or key sequence vector, which is treated as a keyboard
+ macro
+
+ * A keymap to define a prefix key
+
+ * A symbol so that when the key is looked up, the symbol stands for
+ its function definition, which should at that time be one of the
+ above, or another symbol whose function definition is used, and so
+ on
+
+ * A cons, `(string . defn)', meaning that DEFN is the definition
+ (DEFN should be a valid definition in its own right)
+
+ * A cons, `(keymap . char)', meaning use the definition of CHAR in
+ map KEYMAP
+
+ For backward compatibility, XEmacs allows you to specify key
+sequences as strings. However, the preferred method is to use the
+representations of key sequences as vectors of keystrokes. *Note
+Keystrokes::, for more information about the rules for constructing key
+sequences.
+
+ Emacs allows you to abbreviate representations for key sequences in
+most places where there is no ambiguity. Here are some rules for
+abbreviation:
+
+ * The keysym by itself is equivalent to a list of just that keysym,
+ i.e., `f1' is equivalent to `(f1)'.
+
+ * A keystroke by itself is equivalent to a vector containing just
+ that keystroke, i.e., `(control a)' is equivalent to `[(control
+ a)]'.
+
+ * You can use ASCII codes for keysyms that have them. i.e., `65' is
+ equivalent to `A'. (This is not so much an abbreviation as an
+ alternate representation.)
+
+ Here are some examples of programmatically binding keys:
+
+
+ ;;; Bind `my-command' to <f1>
+ (global-set-key 'f1 'my-command)
+
+ ;;; Bind `my-command' to Shift-f1
+ (global-set-key '(shift f1) 'my-command)
+
+ ;;; Bind `my-command' to C-c Shift-f1
+ (global-set-key '[(control c) (shift f1)] 'my-command)
+
+ ;;; Bind `my-command' to the middle mouse button.
+ (global-set-key 'button2 'my-command)
+
+ ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
+ ;;; in the keymap that is in force when you are running `dired'.
+ (define-key dired-mode-map '(meta control button3) 'my-command)
+
+\1f
+File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding
+
+Using Strings for Changing Key Bindings
+.......................................
+
+ For backward compatibility, you can still use strings to represent
+key sequences. Thus you can use commands like the following:
+
+ ;;; Bind `end-of-line' to C-f
+ (global-set-key "\C-f" 'end-of-line)
+
+ Note, however, that in some cases you may be binding more than one
+key sequence by using a single command. This situation can arise
+because in ASCII, `C-i' and <TAB> have the same representation.
+Therefore, when Emacs sees:
+
+ (global-set-key "\C-i" 'end-of-line)
+
+ it is unclear whether the user intended to bind `C-i' or <TAB>. The
+solution XEmacs adopts is to bind both of these key sequences.
+
+ After binding a command to two key sequences with a form like:
+
+ (define-key global-map "\^X\^I" 'command-1)
+
+ it is possible to redefine only one of those sequences like so:
+
+ (define-key global-map [(control x) (control i)] 'command-2)
+ (define-key global-map [(control x) tab] 'command-3)
+
+ This applies only when running under a window system. If you are
+talking to Emacs through an ASCII-only channel, you do not get any of
+these features.
+
+ Here is a table of pairs of key sequences that behave in a similar
+fashion:
+
+ control h backspace
+ control l clear
+ control i tab
+ control m return
+ control j linefeed
+ control [ escape
+ control @ control space
+
+\1f
File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings
Disabling Commands
You type something other than `yes' or `no'
\1f
-File: xemacs.info, Node: Faces, Next: X Resources, Prev: Audible Bell, Up: Customization
+File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization
Faces
=====
otherwise, it is changed in all frames.
\1f
-File: xemacs.info, Node: X Resources, Prev: Faces, Up: Customization
+File: xemacs.info, Node: Frame Components, Next: X Resources, Prev: Faces, Up: Customization
+
+Frame Components
+================
+
+ You can control the presence and position of most frame components,
+such as the menubar, toolbars, and gutters.
+
+ This section is not written yet. Try the Lisp Reference Manual:
+*Note Menubar: (lispref)Menubar, *Note Toolbar Intro: (lispref)Toolbar
+Intro, and *Note Gutter Intro: (lispref)Gutter Intro.
+
+\1f
+File: xemacs.info, Node: X Resources, Prev: Frame Components, Up: Customization
X Resources
===========
resources are used to initialize the variables
`x-pointer-foreground-color' and `x-pointer-background-color'.
-\1f
-File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources
-
-Face Resources
---------------
-
- The attributes of faces are also per-frame. They can be specified as:
-
- Emacs.FACE_NAME.parameter: value
-
-or
-
- Emacs*FRAME_NAME.FACE_NAME.parameter: value
-
-Faces accept the following resources:
-
-`attributeFont' (class `AttributeFont'): font-name
- The font of this face.
-
-`attributeForeground' (class `AttributeForeground'): color-name
-`attributeBackground' (class `AttributeBackground'): color-name
- The foreground and background colors of this face.
-
-`attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name
- The name of an XBM file (or XPM file, if your version of Emacs
- supports XPM), to use as a background stipple.
-
-`attributeUnderline' (class `AttributeUnderline'): boolean
- Whether text in this face should be underlined.
-
- All text is displayed in some face, defaulting to the face named
-`default'. To set the font of normal text, use
-`Emacs*default.attributeFont'. To set it in the frame named `fred', use
-`Emacs*fred.default.attributeFont'.
-
- These are the names of the predefined faces:
-
-`default'
- Everything inherits from this.
-
-`bold'
- If this is not specified in the resource database, Emacs tries to
- find a bold version of the font of the default face.
-
-`italic'
- If this is not specified in the resource database, Emacs tries to
- find an italic version of the font of the default face.
-
-`bold-italic'
- If this is not specified in the resource database, Emacs tries to
- find a bold-italic version of the font of the default face.
-
-`modeline'
- This is the face that the modeline is displayed in. If not
- specified in the resource database, it is determined from the
- default face by reversing the foreground and background colors.
-
-`highlight'
- This is the face that highlighted extents (for example, Info
- cross-references and possible completions, when the mouse passes
- over them) are displayed in.
-
-`left-margin'
-`right-margin'
- These are the faces that the left and right annotation margins are
- displayed in.
-
-`zmacs-region'
- This is the face that mouse selections are displayed in.
-
-`isearch'
- This is the face that the matched text being searched for is
- displayed in.
-
-`info-node'
- This is the face of info menu items. If unspecified, it is copied
- from `bold-italic'.
-
-`info-xref'
- This is the face of info cross-references. If unspecified, it is
- copied from `bold'. (Note that, when the mouse passes over a
- cross-reference, the cross-reference's face is determined from a
- combination of the `info-xref' and `highlight' faces.)
-
- Other packages might define their own faces; to see a list of all
-faces, use any of the interactive face-manipulation commands such as
-`set-face-font' and type `?' when you are prompted for the name of a
-face.
-
- If the `bold', `italic', and `bold-italic' faces are not specified
-in the resource database, then XEmacs attempts to derive them from the
-font of the default face. It can only succeed at this if you have
-specified the default font using the XLFD (X Logical Font Description)
-format, which looks like
-
- *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
-
-If you use any of the other, less strict font name formats, some of
-which look like
-
- lucidasanstypewriter-12
- fixed
- 9x13
-
- then XEmacs won't be able to guess the names of the bold and italic
-versions. All X fonts can be referred to via XLFD-style names, so you
-should use those forms. See the man pages for `X(1)', `xlsfonts(1)',
-and `xfontsel(1)'.
-
-\1f
-File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources
-
-Widgets
--------
-
- There are several structural widgets between the terminal EmacsFrame
-widget and the top level ApplicationShell; the exact names and types of
-these widgets change from release to release (for example, they changed
-between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
-subject to further change in the future, so you should avoid mentioning
-them in your resource database. The above-mentioned syntaxes should be
-forward- compatible. As of 19.13, the exact widget hierarchy is as
-follows:
-
- INVOCATION-NAME "shell" "container" FRAME-NAME
- x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
-
- where INVOCATION-NAME is the terminal component of the name of the
-XEmacs executable (usually `xemacs'), and `x-emacs-application-class'
-is generally `Emacs'.
-
-\1f
-File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources
-
-Menubar Resources
------------------
-
- As the menubar is implemented as a widget which is not a part of
-XEmacs proper, it does not use the fac" mechanism for specifying fonts
-and colors: It uses whatever resources are appropriate to the type of
-widget which is used to implement it.
-
- If Emacs was compiled to use only the Motif-lookalike menu widgets,
-then one way to specify the font of the menubar would be
-
- Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
-
- If the Motif library is being used, then one would have to use
-
- Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
-
- because the Motif library uses the `fontList' resource name instead
-of `font', which has subtly different semantics.
-
- The same is true of the scrollbars: They accept whichever resources
-are appropriate for the toolkit in use.
-
-\1f
-File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top
-
-Quitting and Aborting
-=====================
-
-`C-g'
- Quit. Cancel running or partially typed command.
-
-`C-]'
- Abort innermost recursive editing level and cancel the command
- which invoked it (`abort-recursive-edit').
-
-`M-x top-level'
- Abort all recursive editing levels that are currently executing.
-
-`C-x u'
- Cancel an already-executed command, usually (`undo').
-
- There are two ways of cancelling commands which are not finished
-executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
-top-level'. Quitting is cancelling a partially typed command or one
-which is already running. Aborting is getting out of a recursive
-editing level and cancelling the command that invoked the recursive
-edit.
-
- Quitting with `C-g' is used for getting rid of a partially typed
-command or a numeric argument that you don't want. It also stops a
-running command in the middle in a relatively safe way, so you can use
-it if you accidentally start executing a command that takes a long
-time. In particular, it is safe to quit out of killing; either your
-text will ALL still be there, or it will ALL be in the kill ring (or
-maybe both). Quitting an incremental search does special things
-documented under searching; in general, it may take two successive
-`C-g' characters to get out of a search. `C-g' works by setting the
-variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
-checks this variable frequently and quits if it is non-`nil'. `C-g' is
-only actually executed as a command if it is typed while Emacs is
-waiting for input.
-
- If you quit twice in a row before the first `C-g' is recognized, you
-activate the "emergency escape" feature and return to the shell. *Note
-Emergency Escape::.
-
- You can use `C-]' (`abort-recursive-edit') to get out of a recursive
-editing level and cancel the command which invoked it. Quitting with
-`C-g' does not do this, and could not do this because it is used to
-cancel a partially typed command within the recursive editing level.
-Both operations are useful. For example, if you are in the Emacs
-debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
-argument, you can cancel that argument with `C-g' and remain in the
-debugger.
-
- The command `M-x top-level' is equivalent to "enough" `C-]' commands
-to get you out of all the levels of recursive edits that you are in.
-`C-]' only gets you out one level at a time, but `M-x top-level' goes
-out all levels at once. Both `C-]' and `M-x top-level' are like all
-other commands and unlike `C-g' in that they are effective only when
-Emacs is ready for a command. `C-]' is an ordinary key and has its
-meaning only because of its binding in the keymap. *Note Recursive
-Edit::.
-
- `C-x u' (`undo') is not strictly speaking a way of cancelling a
-command, but you can think of it as cancelling a command already
-finished executing. *Note Undo::.
-
-\1f
-File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top
-
-Dealing With Emacs Trouble
-==========================
-
- This section describes various conditions in which Emacs fails to
-work, and how to recognize them and correct them.
-
-* Menu:
-
-* Stuck Recursive:: `[...]' in mode line around the parentheses.
-* Screen Garbled:: Garbage on the screen.
-* Text Garbled:: Garbage in the text.
-* Unasked-for Search:: Spontaneous entry to incremental search.
-* Emergency Escape:: Emergency escape---
- What to do if Emacs stops responding.
-* Total Frustration:: When you are at your wits' end.
-
-\1f
-File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage
-
-Recursive Editing Levels
-------------------------
-
- Recursive editing levels are important and useful features of Emacs,
-but they can seem like malfunctions to the user who does not understand
-them.
-
- If the mode line has square brackets `[...]' around the parentheses
-that contain the names of the major and minor modes, you have entered a
-recursive editing level. If you did not do this on purpose, or if you
-don't understand what that means, you should just get out of the
-recursive editing level. To do so, type `M-x top-level'. This is
-called getting back to top level. *Note Recursive Edit::.
-
-\1f
-File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage
-
-Garbage on the Screen
----------------------
-
- If the data on the screen looks wrong, the first thing to do is see
-whether the text is actually wrong. Type `C-l', to redisplay the
-entire screen. If the text appears correct after this, the problem was
-entirely in the previous screen update.
-
- Display updating problems often result from an incorrect termcap
-entry for the terminal you are using. The file `etc/TERMS' in the Emacs
-distribution gives the fixes for known problems of this sort.
-`INSTALL' contains general advice for these problems in one of its
-sections. Very likely there is simply insufficient padding for certain
-display operations. To investigate the possibility that you have this
-sort of problem, try Emacs on another terminal made by a different
-manufacturer. If problems happen frequently on one kind of terminal but
-not another kind, the real problem is likely to be a bad termcap entry,
-though it could also be due to a bug in Emacs that appears for terminals
-that have or lack specific features.
-
-\1f
-File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage
-
-Garbage in the Text
--------------------
-
- If `C-l' shows that the text is wrong, try undoing the changes to it
-using `C-x u' until it gets back to a state you consider correct. Also
-try `C-h l' to find out what command you typed to produce the observed
-results.
-
- If a large portion of text appears to be missing at the beginning or
-end of the buffer, check for the word `Narrow' in the mode line. If it
-appears, the text is still present, but marked off-limits. To make it
-visible again, type `C-x n w'. *Note Narrowing::.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources
+
+Face Resources
+--------------
+
+ The attributes of faces are also per-frame. They can be specified as:
+
+ Emacs.FACE_NAME.parameter: value
+
+or
+
+ Emacs*FRAME_NAME.FACE_NAME.parameter: value
+
+Faces accept the following resources:
+
+`attributeFont' (class `AttributeFont'): font-name
+ The font of this face.
+
+`attributeForeground' (class `AttributeForeground'): color-name
+`attributeBackground' (class `AttributeBackground'): color-name
+ The foreground and background colors of this face.
+
+`attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name
+ The name of an XBM file (or XPM file, if your version of Emacs
+ supports XPM), to use as a background stipple.
+
+`attributeUnderline' (class `AttributeUnderline'): boolean
+ Whether text in this face should be underlined.
+
+ All text is displayed in some face, defaulting to the face named
+`default'. To set the font of normal text, use
+`Emacs*default.attributeFont'. To set it in the frame named `fred', use
+`Emacs*fred.default.attributeFont'.
+
+ These are the names of the predefined faces:
+
+`default'
+ Everything inherits from this.
+
+`bold'
+ If this is not specified in the resource database, Emacs tries to
+ find a bold version of the font of the default face.
+
+`italic'
+ If this is not specified in the resource database, Emacs tries to
+ find an italic version of the font of the default face.
+
+`bold-italic'
+ If this is not specified in the resource database, Emacs tries to
+ find a bold-italic version of the font of the default face.
+
+`modeline'
+ This is the face that the modeline is displayed in. If not
+ specified in the resource database, it is determined from the
+ default face by reversing the foreground and background colors.
+
+`highlight'
+ This is the face that highlighted extents (for example, Info
+ cross-references and possible completions, when the mouse passes
+ over them) are displayed in.
+
+`left-margin'
+`right-margin'
+ These are the faces that the left and right annotation margins are
+ displayed in.
+
+`zmacs-region'
+ This is the face that mouse selections are displayed in.
+
+`isearch'
+ This is the face that the matched text being searched for is
+ displayed in.
+
+`info-node'
+ This is the face of info menu items. If unspecified, it is copied
+ from `bold-italic'.
+
+`info-xref'
+ This is the face of info cross-references. If unspecified, it is
+ copied from `bold'. (Note that, when the mouse passes over a
+ cross-reference, the cross-reference's face is determined from a
+ combination of the `info-xref' and `highlight' faces.)
+
+ Other packages might define their own faces; to see a list of all
+faces, use any of the interactive face-manipulation commands such as
+`set-face-font' and type `?' when you are prompted for the name of a
+face.
+
+ If the `bold', `italic', and `bold-italic' faces are not specified
+in the resource database, then XEmacs attempts to derive them from the
+font of the default face. It can only succeed at this if you have
+specified the default font using the XLFD (X Logical Font Description)
+format, which looks like
+
+ *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+If you use any of the other, less strict font name formats, some of
+which look like
+
+ lucidasanstypewriter-12
+ fixed
+ 9x13
+
+ then XEmacs won't be able to guess the names of the bold and italic
+versions. All X fonts can be referred to via XLFD-style names, so you
+should use those forms. See the man pages for `X(1)', `xlsfonts(1)',
+and `xfontsel(1)'.
+
+\1f
+File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources
+
+Widgets
+-------
+
+ There are several structural widgets between the terminal EmacsFrame
+widget and the top level ApplicationShell; the exact names and types of
+these widgets change from release to release (for example, they changed
+between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
+subject to further change in the future, so you should avoid mentioning
+them in your resource database. The above-mentioned syntaxes should be
+forward- compatible. As of 19.13, the exact widget hierarchy is as
+follows:
+
+ INVOCATION-NAME "shell" "container" FRAME-NAME
+ x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
+
+ where INVOCATION-NAME is the terminal component of the name of the
+XEmacs executable (usually `xemacs'), and `x-emacs-application-class'
+is generally `Emacs'.
+
+\1f
+File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources
+
+Menubar Resources
+-----------------
+
+ As the menubar is implemented as a widget which is not a part of
+XEmacs proper, it does not use the face mechanism for specifying fonts
+and colors: It uses whatever resources are appropriate to the type of
+widget which is used to implement it.
+
+ If Emacs was compiled to use only the Motif-lookalike menu widgets,
+then one way to specify the font of the menubar would be
+
+ Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+ If the Motif library is being used, then one would have to use
+
+ Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+ because the Motif library uses the `fontList' resource name instead
+of `font', which has subtly different semantics.
+
+ The same is true of the scrollbars: They accept whichever resources
+are appropriate for the toolkit in use.
+
+\1f
+File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top
+
+Quitting and Aborting
+=====================
+
+`C-g'
+ Quit. Cancel running or partially typed command.
+
+`C-]'
+ Abort innermost recursive editing level and cancel the command
+ which invoked it (`abort-recursive-edit').
+
+`M-x top-level'
+ Abort all recursive editing levels that are currently executing.
+
+`C-x u'
+ Cancel an already-executed command, usually (`undo').
+
+ There are two ways of cancelling commands which are not finished
+executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
+top-level'. Quitting is cancelling a partially typed command or one
+which is already running. Aborting is getting out of a recursive
+editing level and cancelling the command that invoked the recursive
+edit.
+
+ Quitting with `C-g' is used for getting rid of a partially typed
+command or a numeric argument that you don't want. It also stops a
+running command in the middle in a relatively safe way, so you can use
+it if you accidentally start executing a command that takes a long
+time. In particular, it is safe to quit out of killing; either your
+text will ALL still be there, or it will ALL be in the kill ring (or
+maybe both). Quitting an incremental search does special things
+documented under searching; in general, it may take two successive
+`C-g' characters to get out of a search. `C-g' works by setting the
+variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
+checks this variable frequently and quits if it is non-`nil'. `C-g' is
+only actually executed as a command if it is typed while Emacs is
+waiting for input.
+
+ If you quit twice in a row before the first `C-g' is recognized, you
+activate the "emergency escape" feature and return to the shell. *Note
+Emergency Escape::.
+
+ You can use `C-]' (`abort-recursive-edit') to get out of a recursive
+editing level and cancel the command which invoked it. Quitting with
+`C-g' does not do this, and could not do this because it is used to
+cancel a partially typed command within the recursive editing level.
+Both operations are useful. For example, if you are in the Emacs
+debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
+argument, you can cancel that argument with `C-g' and remain in the
+debugger.
+
+ The command `M-x top-level' is equivalent to "enough" `C-]' commands
+to get you out of all the levels of recursive edits that you are in.
+`C-]' only gets you out one level at a time, but `M-x top-level' goes
+out all levels at once. Both `C-]' and `M-x top-level' are like all
+other commands and unlike `C-g' in that they are effective only when
+Emacs is ready for a command. `C-]' is an ordinary key and has its
+meaning only because of its binding in the keymap. *Note Recursive
+Edit::.
+
+ `C-x u' (`undo') is not strictly speaking a way of cancelling a
+command, but you can think of it as cancelling a command already
+finished executing. *Note Undo::.
+
+\1f
+File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top
+
+Dealing With Emacs Trouble
+==========================
+
+ This section describes various conditions in which Emacs fails to
+work, and how to recognize them and correct them.
+
+* Menu:
+
+* Stuck Recursive:: `[...]' in mode line around the parentheses.
+* Screen Garbled:: Garbage on the screen.
+* Text Garbled:: Garbage in the text.
+* Unasked-for Search:: Spontaneous entry to incremental search.
+* Emergency Escape:: Emergency escape---
+ What to do if Emacs stops responding.
+* Total Frustration:: When you are at your wits' end.
+
+\1f
+File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage
+
+Recursive Editing Levels
+------------------------
+
+ Recursive editing levels are important and useful features of Emacs,
+but they can seem like malfunctions to the user who does not understand
+them.
+
+ If the mode line has square brackets `[...]' around the parentheses
+that contain the names of the major and minor modes, you have entered a
+recursive editing level. If you did not do this on purpose, or if you
+don't understand what that means, you should just get out of the
+recursive editing level. To do so, type `M-x top-level'. This is
+called getting back to top level. *Note Recursive Edit::.
+
+\1f
+File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage
+
+Garbage on the Screen
+---------------------
+
+ If the data on the screen looks wrong, the first thing to do is see
+whether the text is actually wrong. Type `C-l', to redisplay the
+entire screen. If the text appears correct after this, the problem was
+entirely in the previous screen update.
+
+ Display updating problems often result from an incorrect termcap
+entry for the terminal you are using. The file `etc/TERMS' in the Emacs
+distribution gives the fixes for known problems of this sort.
+`INSTALL' contains general advice for these problems in one of its
+sections. Very likely there is simply insufficient padding for certain
+display operations. To investigate the possibility that you have this
+sort of problem, try Emacs on another terminal made by a different
+manufacturer. If problems happen frequently on one kind of terminal but
+not another kind, the real problem is likely to be a bad termcap entry,
+though it could also be due to a bug in Emacs that appears for terminals
+that have or lack specific features.
+
+\1f
+File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage
+
+Garbage in the Text
+-------------------
+
+ If `C-l' shows that the text is wrong, try undoing the changes to it
+using `C-x u' until it gets back to a state you consider correct. Also
+try `C-h l' to find out what command you typed to produce the observed
+results.
+
+ If a large portion of text appears to be missing at the beginning or
+end of the buffer, check for the word `Narrow' in the mode line. If it
+appears, the text is still present, but marked off-limits. To make it
+visible again, type `C-x n w'. *Note Narrowing::.
+
+\1f
File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage
Spontaneous Entry to Incremental Search
FTP server. It provides some introductory information and help for
initial configuration problems.
-\1f
-File: xemacs.info, Node: Glossary, Next: Manifesto, Prev: Intro, Up: Top
-
-Glossary
-********
-
-Abbrev
- An abbrev is a text string which expands into a different text
- string when present in the buffer. For example, you might define
- a short word as an abbrev for a long phrase that you want to insert
- frequently. *Note Abbrevs::.
-
-Aborting
- Aborting means getting out of a recursive edit (q.v.). You can use
- the commands `C-]' and `M-x top-level' for this. *Note Quitting::.
-
-Auto Fill mode
- Auto Fill mode is a minor mode in which text you insert is
- automatically broken into lines of fixed width. *Note Filling::.
-
-Auto Saving
- Auto saving means that Emacs automatically stores the contents of
- an Emacs buffer in a specially-named file so the information will
- not be lost if the buffer is lost due to a system error or user
- error. *Note Auto Save::.
-
-Backup File
- A backup file records the contents that a file had before the
- current editing session. Emacs creates backup files automatically
- to help you track down or cancel changes you later regret. *Note
- Backup::.
-
-Balance Parentheses
- Emacs can balance parentheses manually or automatically. Manual
- balancing is done by the commands to move over balanced expressions
- (*note Lists::). Automatic balancing is done by blinking the
- parenthesis that matches one just inserted (*note Matching Parens:
- Matching.).
-
-Bind
- To bind a key is to change its binding (q.v.). *Note Rebinding::.
-
-Binding
- A key gets its meaning in Emacs by having a binding which is a
- command (q.v.), a Lisp function that is run when the key is typed.
- *Note Binding: Commands. Customization often involves rebinding a
- character to a different command function. The bindings of all
- keys are recorded in the keymaps (q.v.). *Note Keymaps::.
-
-Blank Lines
- Blank lines are lines that contain only whitespace. Emacs has
- several commands for operating on the blank lines in a buffer.
-
-Buffer
- The buffer is the basic editing unit; one buffer corresponds to one
- piece of text being edited. You can have several buffers, but at
- any time you are editing only one, the `selected' buffer, though
- several buffers can be visible when you are using multiple
- windows. *Note Buffers::.
-
-Buffer Selection History
- Emacs keeps a buffer selection history which records how recently
- each Emacs buffer was selected. Emacs uses this list when
- choosing a buffer to select. *Note Buffers::.
-
-C-
- `C' in the name of a character is an abbreviation for Control.
- *Note C-: Keystrokes.
-
-C-M-
- `C-M-' in the name of a character is an abbreviation for
- Control-Meta. *Note C-M-: Keystrokes.
-
-Case Conversion
- Case conversion means changing text from upper case to lower case
- or vice versa. *Note Case::, for the commands for case conversion.
-
-Characters
- Characters form the contents of an Emacs buffer; also, Emacs
- commands are invoked by keys (q.v.), which are sequences of one or
- more characters. *Note Keystrokes::.
-
-Command
- A command is a Lisp function specially defined to be able to serve
- as a key binding in Emacs. When you type a key (q.v.), Emacs
- looks up its binding (q.v.) in the relevant keymaps (q.v.) to find
- the command to run. *Note Commands::.
-
-Command Name
- A command name is the name of a Lisp symbol which is a command
- (*note Commands::). You can invoke any command by its name using
- `M-x' (*note M-x::).
-
-Comments
- A comment is text in a program which is intended only for the
- people reading the program, and is marked specially so that it
- will be ignored when the program is loaded or compiled. Emacs
- offers special commands for creating, aligning, and killing
- comments. *Note Comments::.
-
-Compilation
- Compilation is the process of creating an executable program from
- source code. Emacs has commands for compiling files of Emacs Lisp
- code (*note Lisp Libraries::) and programs in C and other languages
- (*note Compilation::).
-
-Complete Key
- A complete key is a character or sequence of characters which,
- when typed by the user, fully specifies one action to be performed
- by Emacs. For example, `X' and `Control-f' and `Control-x m' are
- keys. Keys derive their meanings from being bound (q.v.) to
- commands (q.v.). Thus, `X' is conventionally bound to a command
- to insert `X' in the buffer; `C-x m' is conventionally bound to a
- command to begin composing a mail message. *Note Keystrokes::.
-
-Completion
- When Emacs automatically fills an abbreviation for a name into the
- entire name, that process is called completion. Completion is
- done for minibuffer (q.v.) arguments when the set of possible
- valid inputs is known; for example, on command names, buffer
- names, and file names. Completion occurs when you type <TAB>,
- <SPC>, or <RET>. *Note Completion::.
-
-Continuation Line
- When a line of text is longer than the width of the frame, it
- takes up more than one screen line when displayed. We say that the
- text line is continued, and all screen lines used for it after the
- first are called continuation lines. *Note Continuation: Basic.
-
-Control-Character
- ASCII characters with octal codes 0 through 037, and also code
- 0177, do not have graphic images assigned to them. These are the
- control characters. Any control character can be typed by holding
- down the <CTRL> key and typing some other character; some have
- special keys on the keyboard. <RET>, <TAB>, <ESC>, <LFD>, and
- <DEL> are all control characters. *Note Keystrokes::.
-
-Copyleft
- A copyleft is a notice giving the public legal permission to
- redistribute a program or other work of art. Copylefts are used
- by leftists to enrich the public just as copyrights are used by
- rightists to gain power over the public.
-
-Current Buffer
- The current buffer in Emacs is the Emacs buffer on which most
- editing commands operate. You can select any Emacs buffer as the
- current one. *Note Buffers::.
-
-Current Line
- The line point is on (*note Point::).
-
-Current Paragraph
- The paragraph that point is in. If point is between paragraphs,
- the current paragraph is the one that follows point. *Note
- Paragraphs::.
-
-Current Defun
- The defun (q.v.) that point is in. If point is between defuns, the
- current defun is the one that follows point. *Note Defuns::.
-
-Cursor
- The cursor is the rectangle on the screen which indicates the
- position called point (q.v.) at which insertion and deletion takes
- place. The cursor is on or under the character that follows
- point. Often people speak of `the cursor' when, strictly
- speaking, they mean `point'. *Note Cursor: Basic.
-
-Customization
- Customization is making minor changes in the way Emacs works. It
- is often done by setting variables (*note Variables::) or by
- rebinding keys (*note Keymaps::).
-
-Default Argument
- The default for an argument is the value that is used if you do not
- specify one. When Emacs prompts you in the minibuffer for an
- argument, the default argument is used if you just type <RET>.
- *Note Minibuffer::.
-
-Default Directory
- When you specify a file name that does not start with `/' or `~',
- it is interpreted relative to the current buffer's default
- directory. *Note Default Directory: Minibuffer File.
-
-Defun
- A defun is a list at the top level of parenthesis or bracket
- structure in a program. It is so named because most such lists in
- Lisp programs are calls to the Lisp function `defun'. *Note
- Defuns::.
-
-<DEL>
- The <DEL> character runs the command that deletes one character of
- text. *Note DEL: Basic.
-
-Deletion
- Deleting text means erasing it without saving it. Emacs deletes
- text only when it is expected not to be worth saving (all
- whitespace, or only one character). The alternative is killing
- (q.v.). *Note Deletion: Killing.
-
-Deletion of Files
- Deleting a file means removing it from the file system. *Note
- Misc File Ops::.
-
-Deletion of Messages
- Deleting a message means flagging it to be eliminated from your
- mail file. Until the mail file is expunged, you can undo this by
- undeleting the message.
-
-Deletion of Frames
- When working under the multi-frame X-based version of XEmacs, you
- can delete individual frames using the Close menu item from the
- File menu.
-
-Deletion of Windows
- When you delete a subwindow of an Emacs frame, you eliminate it
- from the frame. Other windows expand to use up the space. The
- deleted window can never come back, but no actual text is lost.
- *Note Windows::.
-
-Directory
- Files in the Unix file system are grouped into file directories.
- *Note Directories: ListDir.
-
-Dired
- Dired is the Emacs facility that displays the contents of a file
- directory and allows you to "edit the directory", performing
- operations on the files in the directory. *Note Dired::.
-
-Disabled Command
- A disabled command is one that you may not run without special
- confirmation. Commands are usually disabled because they are
- confusing for beginning users. *Note Disabling::.
-
-Dribble File
- A file into which Emacs writes all the characters that the user
- types on the keyboard. Dribble files are used to make a record for
- debugging Emacs bugs. Emacs does not make a dribble file unless
- you tell it to. *Note Bugs::.
-
-Echo Area
- The area at the bottom of the Emacs frame which is used for
- echoing the arguments to commands, for asking questions, and for
- printing brief messages (including error messages). *Note Echo
- Area::.
-
-Echoing
- Echoing refers to acknowledging the receipt of commands by
- displaying them (in the echo area). Emacs never echoes
- single-character keys; longer keys echo only if you pause while
- typing them.
-
-Error
- An error occurs when an Emacs command cannot execute in the current
- circumstances. When an error occurs, execution of the command
- stops (unless the command has been programmed to do otherwise) and
- Emacs reports the error by printing an error message (q.v.).
- Type-ahead is discarded. Then Emacs is ready to read another
- editing command.
-
-Error Messages
- Error messages are single lines of output printed by Emacs when the
- user asks for something impossible to do (such as killing text
- forward when point is at the end of the buffer). They appear in
- the echo area, accompanied by a beep.
-
-<ESC>
- <ESC> is a character used as a prefix for typing Meta characters on
- keyboards lacking a <META> key. Unlike the <META> key (which,
- like the <SHIFT> key, is held down while another character is
- typed), the <ESC> key is pressed and released, and applies to the
- next character typed.
-
-Fill Prefix
- The fill prefix is a string that Emacs enters at the beginning of
- each line when it performs filling. It is not regarded as part of
- the text to be filled. *Note Filling::.
-
-Filling
- Filling text means moving text from line to line so that all the
- lines are approximately the same length. *Note Filling::.
-
-Frame
- When running Emacs on a TTY terminal, "frame" means the terminal's
- screen. When running Emacs under X, you can have multiple frames,
- each corresponding to a top-level X window and each looking like
- the screen on a TTY. Each frame contains one or more
- non-overlapping Emacs windows (possibly with associated
- scrollbars, under X), an echo area, and (under X) possibly a
- menubar.
-
-Global
- Global means `independent of the current environment; in effect
- throughout Emacs'. It is the opposite of local (q.v.). Examples
- of the use of `global' appear below.
-
-Global Abbrev
- A global definition of an abbrev (q.v.) is effective in all major
- modes that do not have local (q.v.) definitions for the same
- abbrev. *Note Abbrevs::.
-
-Global Keymap
- The global keymap (q.v.) contains key bindings that are in effect
- unless local key bindings in a major mode's local keymap (q.v.)
- override them.*Note Keymaps::.
-
-Global Substitution
- Global substitution means replacing each occurrence of one string
- by another string through a large amount of text. *Note Replace::.
-
-Global Variable
- The global value of a variable (q.v.) takes effect in all buffers
- that do not have their own local (q.v.) values for the variable.
- *Note Variables::.
-
-Graphic Character
- Graphic characters are those assigned pictorial images rather than
- just names. All the non-Meta (q.v.) characters except for the
- Control (q.v.) character are graphic characters. These include
- letters, digits, punctuation, and spaces; they do not include
- <RET> or <ESC>. In Emacs, typing a graphic character inserts that
- character (in ordinary editing modes). *Note Basic Editing: Basic.
-
-Grinding
- Grinding means adjusting the indentation in a program to fit the
- nesting structure. *Note Grinding: Indentation.
-
-Hardcopy
- Hardcopy means printed output. Emacs has commands for making
- printed listings of text in Emacs buffers. *Note Hardcopy::.
-
-<HELP>
- You can type <HELP> at any time to ask what options you have, or
- to ask what any command does. <HELP> is really `Control-h'.
- *Note Help::.
-
-Inbox
- An inbox is a file in which mail is delivered by the operating
- system. Some mail handlers transfers mail from inboxes to mail
- files (q.v.) in which the mail is then stored permanently or until
- explicitly deleted.
-
-Indentation
- Indentation means blank space at the beginning of a line. Most
- programming languages have conventions for using indentation to
- illuminate the structure of the program, and Emacs has special
- features to help you set up the correct indentation. *Note
- Indentation::.
-
-Insertion
- Insertion means copying text into the buffer, either from the
- keyboard or from some other place in Emacs.
-
-Justification
- Justification means adding extra spaces to lines of text to make
- them come exactly to a specified width. *Note Justification:
- Filling.
-
-Keyboard Macros
- Keyboard macros are a way of defining new Emacs commands from
- sequences of existing ones, with no need to write a Lisp program.
- *Note Keyboard Macros::.
-
-Key
- A key is a sequence of characters that, when input to Emacs,
- specify or begin to specify a single action for Emacs to perform.
- That is, the sequence is considered a single unit. If the key is
- enough to specify one action, it is a complete key (q.v.); if it
- is less than enough, it is a prefix key (q.v.). *Note
- Keystrokes::.
-
-Keymap
- The keymap is the data structure that records the bindings (q.v.)
- of keys to the commands that they run. For example, the keymap
- binds the character `C-n' to the command function `next-line'.
- *Note Keymaps::.
-
-Kill Ring
- The kill ring is the place where all text you have killed recently
- is saved. You can re-insert any of the killed text still in the
- ring; this is called yanking (q.v.). *Note Yanking::.
-
-Killing
- Killing means erasing text and saving it on the kill ring so it
- can be yanked (q.v.) later. Some other systems call this
- "cutting." Most Emacs commands to erase text do killing, as
- opposed to deletion (q.v.). *Note Killing::.
-
-Killing Jobs
- Killing a job (such as, an invocation of Emacs) means making it
- cease to exist. Any data within it, if not saved in a file, is
- lost. *Note Exiting::.
-
-List
- A list is, approximately, a text string beginning with an open
- parenthesis and ending with the matching close parenthesis. In C
- mode and other non-Lisp modes, groupings surrounded by other kinds
- of matched delimiters appropriate to the language, such as braces,
- are also considered lists. Emacs has special commands for many
- operations on lists. *Note Lists::.
-
-Local
- Local means `in effect only in a particular context'; the relevant
- kind of context is a particular function execution, a particular
- buffer, or a particular major mode. Local is the opposite of
- `global' (q.v.). Specific uses of `local' in Emacs terminology
- appear below.
-
-Local Abbrev
- A local abbrev definition is effective only if a particular major
- mode is selected. In that major mode, it overrides any global
- definition for the same abbrev. *Note Abbrevs::.
-
-Local Keymap
- A local keymap is used in a particular major mode; the key bindings
- (q.v.) in the current local keymap override global bindings of the
- same keys. *Note Keymaps::.
-
-Local Variable
- A local value of a variable (q.v.) applies to only one buffer.
- *Note Locals::.
-
-M-
- `M-' in the name of a character is an abbreviation for <META>, one
- of the modifier keys that can accompany any character. *Note
- Keystrokes::.
-
-M-C-
- `M-C-' in the name of a character is an abbreviation for
- Control-Meta; it means the same thing as `C-M-'. If your terminal
- lacks a real <META> key, you type a Control-Meta character by
- typing <ESC> and then typing the corresponding Control character.
- *Note C-M-: Keystrokes.
-
-M-x
- `M-x' is the key which is used to call an Emacs command by name.
- You use it to call commands that are not bound to keys. *Note
- M-x::.
-
-Mail
- Mail means messages sent from one user to another through the
- computer system, to be read at the recipient's convenience. Emacs
- has commands for composing and sending mail, and for reading and
- editing the mail you have received. *Note Sending Mail::.
-
-Major Mode
- The major modes are a mutually exclusive set of options each of
- which configures Emacs for editing a certain sort of text.
- Ideally, each programming language has its own major mode. *Note
- Major Modes::.
-
-Mark
- The mark points to a position in the text. It specifies one end
- of the region (q.v.), point being the other end. Many commands
- operate on the whole region, that is, all the text from point to
- the mark. *Note Mark::.
-
-Mark Ring
- The mark ring is used to hold several recent previous locations of
- the mark, just in case you want to move back to them. *Note Mark
- Ring::.
-
-Message
- See `mail'.
-
-Meta
- Meta is the name of a modifier bit which a command character may
- have. It is present in a character if the character is typed with
- the <META> key held down. Such characters are given names that
- start with `Meta-'. For example, `Meta-<' is typed by holding down
- <META> and at the same time typing `<' (which itself is done, on
- most terminals, by holding down <SHIFT> and typing `,'). *Note
- Meta: Keystrokes.
-
-Meta Character
- A Meta character is one whose character code includes the Meta bit.
-
-Minibuffer
- The minibuffer is the window that Emacs displays inside the echo
- area (q.v.) when it prompts you for arguments to commands. *Note
- Minibuffer::.
-
-Minor Mode
- A minor mode is an optional feature of Emacs which can be switched
- on or off independent of the major mode. Each minor mode has a
- command to turn it on or off. *Note Minor Modes::.
-
-Mode Line
- The mode line is the line at the bottom of each text window (q.v.),
- which gives status information on the buffer displayed in that
- window. *Note Mode Line::.
-
-Modified Buffer
- A buffer (q.v.) is modified if its text has been changed since the
- last time the buffer was saved (or since it was created, if it has
- never been saved). *Note Saving::.
-
-Moving Text
- Moving text means erasing it from one place and inserting it in
- another. This is done by killing (q.v.) and then yanking (q.v.).
- *Note Killing::.
-
-Named Mark
- A named mark is a register (q.v.) in its role of recording a
- location in text so that you can move point to that location.
- *Note Registers::.
-
-Narrowing
- Narrowing means creating a restriction (q.v.) that limits editing
- in the current buffer to only a part of the text in the buffer.
- Text outside that part is inaccessible to the user until the
- boundaries are widened again, but it is still there, and saving
- the file saves the invisible text. *Note Narrowing::.
-
-Newline
- <LFD> characters in the buffer terminate lines of text and are
- called newlines. *Note Newline: Keystrokes.
-
-Numeric Argument
- A numeric argument is a number, specified before a command, to
- change the effect of the command. Often the numeric argument
- serves as a repeat count. *Note Arguments::.
-
-Option
- An option is a variable (q.v.) that allows you to customize Emacs
- by giving it a new value. *Note Variables::.
-
-Overwrite Mode
- Overwrite mode is a minor mode. When it is enabled, ordinary text
- characters replace the existing text after point rather than
- pushing it to the right. *Note Minor Modes::.
-
-Page
- A page is a unit of text, delimited by formfeed characters (ASCII
- Control-L, code 014) coming at the beginning of a line. Some Emacs
- commands are provided for moving over and operating on pages.
- *Note Pages::.
-
-Paragraphs
- Paragraphs are the medium-size unit of English text. There are
- special Emacs commands for moving over and operating on paragraphs.
- *Note Paragraphs::.
-
-Parsing
- We say that Emacs parses words or expressions in the text being
- edited. Really, all it knows how to do is find the other end of a
- word or expression. *Note Syntax::.
-
-Point
- Point is the place in the buffer at which insertion and deletion
- occur. Point is considered to be between two characters, not at
- one character. The terminal's cursor (q.v.) indicates the
- location of point. *Note Point: Basic.
-
-Prefix Key
- A prefix key is a key (q.v.) whose sole function is to introduce a
- set of multi-character keys. `Control-x' is an example of a prefix
- key; any two-character sequence starting with `C-x' is also a
- legitimate key. *Note Keystrokes::.
-
-Prompt
- A prompt is text printed to ask the user for input. Printing a
- prompt is called prompting. Emacs prompts always appear in the
- echo area (q.v.). One kind of prompting happens when the
- minibuffer is used to read an argument (*note Minibuffer::); the
- echoing which happens when you pause in the middle of typing a
- multi-character key is also a kind of prompting (*note Echo
- Area::).
-
-Quitting
- Quitting means cancelling a partially typed command or a running
- command, using `C-g'. *Note Quitting::.
-
-Quoting
- Quoting means depriving a character of its usual special
- significance. In Emacs this is usually done with `Control-q'.
- What constitutes special significance depends on the context and
- on convention. For example, an "ordinary" character as an Emacs
- command inserts itself; so in this context, a special character is
- any character that does not normally insert itself (such as <DEL>,
- for example), and quoting it makes it insert itself as if it were
- not special. Not all contexts allow quoting. *Note Quoting:
- Basic.
-
-Read-only Buffer
- A read-only buffer is one whose text you are not allowed to change.
- Normally Emacs makes buffers read-only when they contain text which
- has a special significance to Emacs, such asDired buffers.
- Visiting a file that is write-protected also makes a read-only
- buffer. *Note Buffers::.
-
-Recursive Editing Level
- A recursive editing level is a state in which part of the
- execution of a command involves asking the user to edit some text.
- This text may or may not be the same as the text to which the
- command was applied. The mode line indicates recursive editing
- levels with square brackets (`[' and `]'). *Note Recursive Edit::.
-
-Redisplay
- Redisplay is the process of correcting the image on the screen to
- correspond to changes that have been made in the text being edited.
- *Note Redisplay: Frame.
-
-Regexp
- See `regular expression'.
-
-Region
- The region is the text between point (q.v.) and the mark (q.v.).
- Many commands operate on the text of the region. *Note Region:
- Mark.
-
-Registers
- Registers are named slots in which text or buffer positions or
- rectangles can be saved for later use. *Note Registers::.
-
-Regular Expression
- A regular expression is a pattern that can match various text
- strings; for example, `l[0-9]+' matches `l' followed by one or more
- digits. *Note Regexps::.
-
-Replacement
- See `global substitution'.
-
-Restriction
- A buffer's restriction is the amount of text, at the beginning or
- the end of the buffer, that is temporarily invisible and
- inaccessible. Giving a buffer a nonzero amount of restriction is
- called narrowing (q.v.). *Note Narrowing::.
-
-<RET>
- <RET> is the character than runs the command to insert a newline
- into the text. It is also used to terminate most arguments read
- in the minibuffer (q.v.). *Note Return: Keystrokes.
-
-Saving
- Saving a buffer means copying its text into the file that was
- visited (q.v.) in that buffer. To actually change a file you have
- edited in Emacs, you have to save it. *Note Saving::.
-
-Scrolling
- Scrolling means shifting the text in the Emacs window to make a
- different part ot the buffer visible. *Note Scrolling: Display.
-
-Searching
- Searching means moving point to the next occurrence of a specified
- string. *Note Search::.
-
-Selecting
- Selecting a buffer means making it the current (q.v.) buffer.
- *Note Selecting: Buffers.
-
-Self-documentation
- Self-documentation is the feature of Emacs which can tell you what
- any command does, or can give you a list of all commands related
- to a topic you specify. You ask for self-documentation with the
- help character, `C-h'. *Note Help::.
-
-Sentences
- Emacs has commands for moving by or killing by sentences. *Note
- Sentences::.
-
-Sexp
- An sexp (short for `s-expression,' itself short for `symbolic
- expression') is the basic syntactic unit of Lisp in its textual
- form: either a list, or Lisp atom. Many Emacs commands operate on
- sexps. The term `sexp' is generalized to languages other than
- Lisp to mean a syntactically recognizable expression. *Note
- Sexps: Lists.
-
-Simultaneous Editing
- Simultaneous editing means two users modifying the same file at
- once. If simultaneous editing is not detected, you may lose your
- work. Emacs detects all cases of simultaneous editing and warns
- the user to investigate them. *Note Simultaneous Editing:
- Interlocking.
-
-String
- A string is a kind of Lisp data object which contains a sequence of
- characters. Many Emacs variables are intended to have strings as
- values. The Lisp syntax for a string consists of the characters in
- the string with a `"' before and another `"' after. Write a `"'
- that is part of the string as `\"' and a `\' that is part of the
- string as `\\'. You can include all other characters, including
- newline, just by writing them inside the string. You can also
- include escape sequences as in C, such as `\n' for newline or
- `\241' using an octal character code.
-
-String Substitution
- See `global substitution'.
-
-Syntax Table
- The syntax table tells Emacs which characters are part of a word,
- which characters balance each other like parentheses, etc. *Note
- Syntax::.
-
-Tag Table
- A tag table is a file that serves as an index to the function
- definitions in one or more other files. *Note Tags::.
-
-Termscript File
- A termscript file contains a record of all characters Emacs sent to
- the terminal. It is used for tracking down bugs in Emacs
- redisplay. Emacs does not make a termscript file unless
- explicitly instructed to do so. *Note Bugs::.
-
-Text
- Text has two meanings (*note Text::):
-
- * Data consisting of a sequence of characters, as opposed to
- binary numbers, images, graphics commands, executable
- programs, and the like. The contents of an Emacs buffer are
- always text in this sense.
-
- * Data consisting of written human language, as opposed to
- programs, or something that follows the stylistic conventions
- of human language.
-
-Top Level
- Top level is the normal state of Emacs, in which you are editing
- the text of the file you have visited. You are at top level
- whenever you are not in a recursive editing level (q.v.) or the
- minibuffer (q.v.), and not in the middle of a command. You can
- get back to top level by aborting (q.v.) and quitting (q.v.).
- *Note Quitting::.
-
-Transposition
- Transposing two units of text means putting each one into the place
- formerly occupied by the other. There are Emacs commands to
- transpose two adjacent characters, words, sexps (q.v.), or lines
- (*note Transpose::).
-
-Truncation
- Truncating text lines in the display means leaving out any text on
- a line that does not fit within the right margin of the window
- displaying it. See also `continuation line'. *Note Truncation:
- Basic.
-
-Undoing
- Undoing means making your previous editing go in reverse, bringing
- back the text that existed earlier in the editing session. *Note
- Undo::.
-
-Variable
- A variable is Lisp object that can store an arbitrary value.
- Emacs uses some variables for internal purposes, and has others
- (known as `options' (q.v.)) you can set to control the behavior of
- Emacs. The variables used in Emacs that you are likely to be
- interested in are listed in the Variables Index of this manual.
- *Note Variables::, for information on variables.
-
-Visiting
- Visiting a file means loading its contents into a buffer (q.v.)
- where they can be edited. *Note Visiting::.
-
-Whitespace
- Whitespace is any run of consecutive formatting characters (spaces,
- tabs, newlines, and backspaces).
-
-Widening
- Widening is removing any restriction (q.v.) on the current buffer;
- it is the opposite of narrowing (q.v.). *Note Narrowing::.
-
-Window
- Emacs divides the frame into one or more windows, each of which can
- display the contents of one buffer (q.v.) at any time. *Note
- Frame::, for basic information on how Emacs uses the frame. *Note
- Windows::, for commands to control the use of windows. Note that if
- you are running Emacs under X, terminology can be confusing: Each
- Emacs frame occupies a separate X window and can, in turn, be
- divided into different subwindows.
-
-Word Abbrev
- Synonymous with `abbrev'.
-
-Word Search
- Word search is searching for a sequence of words, considering the
- punctuation between them as insignificant. *Note Word Search::.
-
-Yanking
- Yanking means reinserting text previously killed. It can be used
- to undo a mistaken kill, or for copying or moving text. Some other
- systems call this "pasting". *Note Yanking::.
-
translation approved by the author instead of in the original English.
\1f
-File: xemacs.info, Node: Manifesto, Next: Key Index, Prev: Glossary, Up: Top
-
-The GNU Manifesto
-*****************
-
-What's GNU? GNU's Not Unix!
-============================
-
- GNU, which stands for GNU's Not Unix, is the name for the complete
-Unix-compatible software system which I am writing so that I can give it
-away free to everyone who can use it. Several other volunteers are
-helping me. Contributions of time, money, programs, and equipment are
-greatly needed.
-
- So far we have an Emacs text editor with Lisp for writing editor
-commands, a source level debugger, a yacc-compatible parser generator,
-a linker, and around 35 utilities. A shell (command interpreter) is
-nearly completed. A new portable optimizing C compiler has compiled
-itself and may be released this year. An initial kernel exists, but
-many more features are needed to emulate Unix. When the kernel and
-compiler are finished, it will be possible to distribute a GNU system
-suitable for program development. We will use TeX as our text
-formatter, but an nroff is being worked on. We will use the free,
-portable X window system as well. After this we will add a portable
-Common Lisp, an Empire game, a spreadsheet, and hundreds of other
-things, plus online documentation. We hope to supply, eventually,
-everything useful that normally comes with a Unix system, and more.
-
- GNU will be able to run Unix programs, but will not be identical to
-Unix. We will make all improvements that are convenient, based on our
-experience with other operating systems. In particular, we plan to
-have longer filenames, file version numbers, a crashproof file system,
-filename completion perhaps, terminal-independent display support, and
-perhaps eventually a Lisp-based window system through which several
-Lisp programs and ordinary Unix programs can share a screen. Both C
-and Lisp will be available as system programming languages. We will
-try to support UUCP, MIT Chaosnet, and Internet protocols for
-communication.
-
- GNU is aimed initially at machines in the 68000/16000 class with
-virtual memory, because they are the easiest machines to make it run
-on. The extra effort to make it run on smaller machines will be left
-to someone who wants to use it on them.
-
- To avoid horrible confusion, please pronounce the `G' in the word
-`GNU' when it is the name of this project.
-
-Why I Must Write GNU
-====================
-
- I consider that the golden rule requires that if I like a program I
-must share it with other people who like it. Software sellers want to
-divide the users and conquer them, making each user agree not to share
-with others. I refuse to break solidarity with other users in this
-way. I cannot in good conscience sign a nondisclosure agreement or a
-software license agreement. For years I worked within the Artificial
-Intelligence Lab to resist such tendencies and other inhospitalities,
-but eventually they had gone too far: I could not remain in an
-institution where such things are done for me against my will.
-
- So that I can continue to use computers without dishonor, I have
-decided to put together a sufficient body of free software so that I
-will be able to get along without any software that is not free. I
-have resigned from the AI lab to deny MIT any legal excuse to prevent
-me from giving GNU away.
-
-Why GNU Will Be Compatible With Unix
-====================================
-
- Unix is not my ideal system, but it is not too bad. The essential
-features of Unix seem to be good ones, and I think I can fill in what
-Unix lacks without spoiling them. And a system compatible with Unix
-would be convenient for many other people to adopt.
-
-How GNU Will Be Available
-=========================
-
- GNU is not in the public domain. Everyone will be permitted to
-modify and redistribute GNU, but no distributor will be allowed to
-restrict its further redistribution. That is to say, proprietary
-modifications will not be allowed. I want to make sure that all
-versions of GNU remain free.
-
-Why Many Other Programmers Want to Help
-=======================================
-
- I have found many other programmers who are excited about GNU and
-want to help.
-
- Many programmers are unhappy about the commercialization of system
-software. It may enable them to make more money, but it requires them
-to feel in conflict with other programmers in general rather than feel
-as comrades. The fundamental act of friendship among programmers is the
-sharing of programs; marketing arrangements now typically used
-essentially forbid programmers to treat others as friends. The
-purchaser of software must choose between friendship and obeying the
-law. Naturally, many decide that friendship is more important. But
-those who believe in law often do not feel at ease with either choice.
-They become cynical and think that programming is just a way of making
-money.
-
- By working on and using GNU rather than proprietary programs, we can
-be hospitable to everyone and obey the law. In addition, GNU serves as
-an example to inspire and a banner to rally others to join us in
-sharing. This can give us a feeling of harmony which is impossible if
-we use software that is not free. For about half the programmers I
-talk to, this is an important happiness that money cannot replace.
-
-How You Can Contribute
-======================
-
- I am asking computer manufacturers for donations of machines and
-money. I'm asking individuals for donations of programs and work.
-
- One consequence you can expect if you donate machines is that GNU
-will run on them at an early date. The machines should be complete,
-ready-to-use systems, approved for use in a residential area, and not
-in need of sophisticated cooling or power.
-
- I have found very many programmers eager to contribute part-time
-work for GNU. For most projects, such part-time distributed work would
-be very hard to coordinate; the independently-written parts would not
-work together. But for the particular task of replacing Unix, this
-problem is absent. A complete Unix system contains hundreds of utility
-programs, each of which is documented separately. Most interface
-specifications are fixed by Unix compatibility. If each contributor
-can write a compatible replacement for a single Unix utility, and make
-it work properly in place of the original on a Unix system, then these
-utilities will work right when put together. Even allowing for Murphy
-to create a few unexpected problems, assembling these components will
-be a feasible task. (The kernel will require closer communication and
-will be worked on by a small, tight group.)
-
- If I get donations of money, I may be able to hire a few people full
-or part time. The salary won't be high by programmers' standards, but
-I'm looking for people for whom building community spirit is as
-important as making money. I view this as a way of enabling dedicated
-people to devote their full energies to working on GNU by sparing them
-the need to make a living in another way.
-
-Why All Computer Users Will Benefit
-===================================
-
- Once GNU is written, everyone will be able to obtain good system
-software free, just like air.
-
- This means much more than just saving everyone the price of a Unix
-license. It means that much wasteful duplication of system programming
-effort will be avoided. This effort can go instead into advancing the
-state of the art.
-
- Complete system sources will be available to everyone. As a result,
-a user who needs changes in the system will always be free to make them
-himself, or hire any available programmer or company to make them for
-him. Users will no longer be at the mercy of one programmer or company
-which owns the sources and is in sole position to make changes.
-
- Schools will be able to provide a much more educational environment
-by encouraging all students to study and improve the system code.
-Harvard's computer lab used to have the policy that no program could be
-installed on the system if its sources were not on public display, and
-upheld it by actually refusing to install certain programs. I was very
-much inspired by this.
-
- Finally, the overhead of considering who owns the system software
-and what one is or is not entitled to do with it will be lifted.
-
- Arrangements to make people pay for using a program, including
-licensing of copies, always incur a tremendous cost to society through
-the cumbersome mechanisms necessary to figure out how much (that is,
-which programs) a person must pay for. And only a police state can
-force everyone to obey them. Consider a space station where air must
-be manufactured at great cost: charging each breather per liter of air
-may be fair, but wearing the metered gas mask all day and all night is
-intolerable even if everyone can afford to pay the air bill. And the
-TV cameras everywhere to see if you ever take the mask off are
-outrageous. It's better to support the air plant with a head tax and
-chuck the masks.
-
- Copying all or parts of a program is as natural to a programmer as
-breathing, and as productive. It ought to be as free.
-
-Some Easily Rebutted Objections to GNU's Goals
-==============================================
-
- "Nobody will use it if it is free, because that means they can't
- rely on any support."
-
- "You have to charge for the program to pay for providing the
- support."
-
- If people would rather pay for GNU plus service than get GNU free
-without service, a company to provide just service to people who have
-obtained GNU free ought to be profitable.
-
- We must distinguish between support in the form of real programming
-work and mere handholding. The former is something one cannot rely on
-from a software vendor. If your problem is not shared by enough
-people, the vendor will tell you to get lost.
-
- If your business needs to be able to rely on support, the only way
-is to have all the necessary sources and tools. Then you can hire any
-available person to fix your problem; you are not at the mercy of any
-individual. With Unix, the price of sources puts this out of
-consideration for most businesses. With GNU this will be easy. It is
-still possible for there to be no available competent person, but this
-problem cannot be blamed on distibution arrangements. GNU does not
-eliminate all the world's problems, only some of them.
-
- Meanwhile, the users who know nothing about computers need
-handholding: doing things for them which they could easily do
-themselves but don't know how.
-
- Such services could be provided by companies that sell just
-hand-holding and repair service. If it is true that users would rather
-spend money and get a product with service, they will also be willing
-to buy the service having got the product free. The service companies
-will compete in quality and price; users will not be tied to any
-particular one. Meanwhile, those of us who don't need the service
-should be able to use the program without paying for the service.
-
- "You cannot reach many people without advertising, and you must
- charge for the program to support that."
-
- "It's no use advertising a program people can get free."
-
- There are various forms of free or very cheap publicity that can be
-used to inform numbers of computer users about something like GNU. But
-it may be true that one can reach more microcomputer users with
-advertising. If this is really so, a business which advertises the
-service of copying and mailing GNU for a fee ought to be successful
-enough to pay for its advertising and more. This way, only the users
-who benefit from the advertising pay for it.
-
- On the other hand, if many people get GNU from their friends, and
-such companies don't succeed, this will show that advertising was not
-really necessary to spread GNU. Why is it that free market advocates
-don't want to let the free market decide this?
-
- "My company needs a proprietary operating system to get a
- competitive edge."
-
- GNU will remove operating system software from the realm of
-competition. You will not be able to get an edge in this area, but
-neither will your competitors be able to get an edge over you. You and
-they will compete in other areas, while benefitting mutually in this
-one. If your business is selling an operating system, you will not
-like GNU, but that's tough on you. If your business is something else,
-GNU can save you from being pushed into the expensive business of
-selling operating systems.
-
- I would like to see GNU development supported by gifts from many
-manufacturers and users, reducing the cost to each.
-
- "Don't programmers deserve a reward for their creativity?"
-
- If anything deserves a reward, it is social contribution.
-Creativity can be a social contribution, but only in so far as society
-is free to use the results. If programmers deserve to be rewarded for
-creating innovative programs, by the same token they deserve to be
-punished if they restrict the use of these programs.
-
- "Shouldn't a programmer be able to ask for a reward for his
- creativity?"
-
- There is nothing wrong with wanting pay for work, or seeking to
-maximize one's income, as long as one does not use means that are
-destructive. But the means customary in the field of software today
-are based on destruction.
-
- Extracting money from users of a program by restricting their use of
-it is destructive because the restrictions reduce the amount and the
-ways that the program can be used. This reduces the amount of wealth
-that humanity derives from the program. When there is a deliberate
-choice to restrict, the harmful consequences are deliberate destruction.
-
- The reason a good citizen does not use such destructive means to
-become wealthier is that, if everyone did so, we would all become
-poorer from the mutual destructiveness. This is Kantian ethics; or,
-the Golden Rule. Since I do not like the consequences that result if
-everyone hoards information, I am required to consider it wrong for one
-to do so. Specifically, the desire to be rewarded for one's creativity
-does not justify depriving the world in general of all or part of that
-creativity.
-
- "Won't programmers starve?"
-
- I could answer that nobody is forced to be a programmer. Most of us
-cannot manage to get any money for standing on the street and making
-faces. But we are not, as a result, condemned to spend our lives
-standing on the street making faces, and starving. We do something
-else.
-
- But that is the wrong answer because it accepts the questioner's
-implicit assumption: that without ownership of software, programmers
-cannot possibly be paid a cent. Supposedly it is all or nothing.
-
- The real reason programmers will not starve is that it will still be
-possible for them to get paid for programming; just not paid as much as
-now.
-
- Restricting copying is not the only basis for business in software.
-It is the most common basis because it brings in the most money. If it
-were prohibited, or rejected by the customer, software business would
-move to other bases of organization which are now used less often.
-There are always numerous ways to organize any kind of business.
-
- Probably programming will not be as lucrative on the new basis as it
-is now. But that is not an argument against the change. It is not
-considered an injustice that sales clerks make the salaries that they
-now do. If programmers made the same, that would not be an injustice
-either. (In practice they would still make considerably more than
-that.)
-
- "Don't people have a right to control how their creativity is
- used?"
-
- "Control over the use of one's ideas" really constitutes control over
-other people's lives; and it is usually used to make their lives more
-difficult.
-
- People who have studied the issue of intellectual property rights
-carefully (such as lawyers) say that there is no intrinsic right to
-intellectual property. The kinds of supposed intellectual property
-rights that the government recognizes were created by specific acts of
-legislation for specific purposes.
-
- For example, the patent system was established to encourage
-inventors to disclose the details of their inventions. Its purpose was
-to help society rather than to help inventors. At the time, the life
-span of 17 years for a patent was short compared with the rate of
-advance of the state of the art. Since patents are an issue only among
-manufacturers, for whom the cost and effort of a license agreement are
-small compared with setting up production, the patents often do not do
-much harm. They do not obstruct most individuals who use patented
-products.
-
- The idea of copyright did not exist in ancient times, when authors
-frequently copied other authors at length in works of non-fiction. This
-practice was useful, and is the only way many authors' works have
-survived even in part. The copyright system was created expressly for
-the purpose of encouraging authorship. In the domain for which it was
-invented--books, which could be copied economically only on a printing
-press--it did little harm, and did not obstruct most of the individuals
-who read the books.
-
- All intellectual property rights are just licenses granted by society
-because it was thought, rightly or wrongly, that society as a whole
-would benefit by granting them. But in any particular situation, we
-have to ask: are we really better off granting such license? What kind
-of act are we licensing a person to do?
-
- The case of programs today is very different from that of books a
-hundred years ago. The fact that the easiest way to copy a program is
-from one neighbor to another, the fact that a program has both source
-code and object code which are distinct, and the fact that a program is
-used rather than read and enjoyed, combine to create a situation in
-which a person who enforces a copyright is harming society as a whole
-both materially and spiritually; in which a person should not do so
-regardless of whether the law enables him to.
-
- "Competition makes things get done better."
-
- The paradigm of competition is a race: by rewarding the winner, we
-encourage everyone to run faster. When capitalism really works this
-way, it does a good job; but its defenders are wrong in assuming it
-always works this way. If the runners forget why the reward is offered
-and become intent on winning, no matter how, they may find other
-strategies--such as, attacking other runners. If the runners get into
-a fist fight, they will all finish late.
-
- Proprietary and secret software is the moral equivalent of runners
-in a fist fight. Sad to say, the only referee we've got does not seem
-to object to fights; he just regulates them ("For every ten yards you
-run, you can fire one shot"). He really ought to break them up, and
-penalize runners for even trying to fight.
-
- "Won't everyone stop programming without a monetary incentive?"
-
- Actually, many people will program with absolutely no monetary
-incentive. Programming has an irresistible fascination for some
-people, usually the people who are best at it. There is no shortage of
-professional musicians who keep at it even though they have no hope of
-making a living that way.
-
- But really this question, though commonly asked, is not appropriate
-to the situation. Pay for programmers will not disappear, only become
-less. So the right question is, will anyone program with a reduced
-monetary incentive? My experience shows that they will.
-
- For more than ten years, many of the world's best programmers worked
-at the Artificial Intelligence Lab for far less money than they could
-have had anywhere else. They got many kinds of non-monetary rewards:
-fame and appreciation, for example. And creativity is also fun, a
-reward in itself.
-
- Then most of them left when offered a chance to do the same
-interesting work for a lot of money.
-
- What the facts show is that people will program for reasons other
-than riches; but if given a chance to make a lot of money as well, they
-will come to expect and demand it. Low-paying organizations do poorly
-in competition with high-paying ones, but they do not have to do badly
-if the high-paying ones are banned.
-
- "We need the programmers desperately. If they demand that we stop
- helping our neighbors, we have to obey."
-
- You're never so desperate that you have to obey this sort of demand.
-Remember: millions for defense, but not a cent for tribute!
-
- "Programmers need to make a living somehow."
-
- In the short run, this is true. However, there are plenty of ways
-that programmers could make a living without selling the right to use a
-program. This way is customary now because it brings programmers and
-businessmen the most money, not because it is the only way to make a
-living. It is easy to find other ways if you want to find them. Here
-are a number of examples.
-
- A manufacturer introducing a new computer will pay for the porting of
-operating systems onto the new hardware.
-
- The sale of teaching, hand-holding, and maintenance services could
-also employ programmers.
-
- People with new ideas could distribute programs as freeware and ask
-for donations from satisfied users or sell hand-holding services. I
-have met people who are already working this way successfully.
-
- Users with related needs can form users' groups and pay dues. A
-group would contract with programming companies to write programs that
-the group's members would like to use.
-
- All sorts of development can be funded with a Software Tax:
-
- Suppose everyone who buys a computer has to pay a certain percent
- of the price as a software tax. The government gives this to an
- agency like the NSF to spend on software development.
-
- But if the computer buyer makes a donation to software development
- himself, he can take a credit against the tax. He can donate to
- the project of his own choosing--often, chosen because he hopes to
- use the results when
-
- it is done. He can take a credit for any amount of donation up to
- the total tax he had to pay.
-
- The total tax rate could be decided by a vote of the payers of the
- tax, weighted according to the amount they will be taxed on.
-
- The consequences:
-
- * The computer-using community supports software development.
-
- * This community decides what level of support is needed.
-
- * Users who care which projects their share is spent on can
- choose this for themselves.
-
- In the long run, making programs free is a step toward the
-post-scarcity world, where nobody will have to work very hard just to
-make a living. People will be free to devote themselves to activities
-that are fun, such as programming, after spending the necessary ten
-hours a week on required tasks such as legislation, family counseling,
-robot repair, and asteroid prospecting. There will be no need to be
-able to make a living from programming.
-
- We have already greatly reduced the amount of work that the whole
-society must do for its actual productivity, but only a little of this
-has translated itself into leisure for workers because much
-nonproductive activity is required to accompany productive activity.
-The main causes of this are bureaucracy and isometric struggles against
-competition. Free software will greatly reduce these drains in the
-area of software production. We must do this, in order for technical
-gains in productivity to translate into less work for us.
-
-\1f
-File: xemacs.info, Node: Key Index, Next: Command Index, Prev: Manifesto, Up: Top
-
-Key (Character) Index
-*********************
-
-* Menu:
-
-* ! (query-replace): Query Replace.
-* " (TeX mode): TeX Editing.
-* , (query-replace): Query Replace.
-* . (Calendar mode): Specified Dates.
-* . (query-replace): Query Replace.
-* ? (Calendar mode): General Calendar.
-* ^ (query-replace): Query Replace.
-* a (Calendar mode): Holidays.
-* button1: Intro to Keystrokes.
-* button1up: Intro to Keystrokes.
-* button2: Intro to Keystrokes.
-* button2up: Intro to Keystrokes.
-* button3: Intro to Keystrokes.
-* button3up: Intro to Keystrokes.
-* C-<: Setting Mark.
-* C->: Setting Mark.
-* C-@ (Calendar mode): Mark and Region.
-* C-\: Select Input Method.
-* C-] <1>: Quitting.
-* C-]: Recursive Edit.
-* C-_: Undo.
-* C-a: Basic.
-* C-a (Calendar mode): Move to Beginning or End.
-* C-b: Basic.
-* C-b (Calendar mode): Calendar Unit Motion.
-* C-c: Key Sequences.
-* C-c ' (Picture mode): Insert in Picture.
-* C-c . (Picture mode): Insert in Picture.
-* C-c / (Picture mode): Insert in Picture.
-* C-c ; (Fortran mode): Fortran Comments.
-* C-c < (Picture mode): Insert in Picture.
-* C-c > (Picture mode): Insert in Picture.
-* C-c \ (Picture mode): Insert in Picture.
-* C-c ^ (Picture mode): Insert in Picture.
-* C-c ` (Picture mode): Insert in Picture.
-* C-c C-\ (Shell mode): Shell Mode.
-* C-c C-b (Outline mode): Outline Motion.
-* C-c C-b (Picture mode): Insert in Picture.
-* C-c C-b (TeX mode): TeX Print.
-* C-c C-c (Edit Abbrevs): Editing Abbrevs.
-* C-c C-c (Edit Tab Stops): Tab Stops.
-* C-c C-c (Mail mode): Mail Mode.
-* C-c C-c (Occur mode): Other Repeating Search.
-* C-c C-c (Shell mode): Shell Mode.
-* C-c C-d (Picture mode): Basic Picture.
-* C-c C-d (Shell mode): Shell Mode.
-* C-c C-f (LaTeX mode): TeX Editing.
-* C-c C-f (Outline mode): Outline Motion.
-* C-c C-f (Picture mode): Insert in Picture.
-* C-c C-f C-c (Mail mode): Mail Mode.
-* C-c C-f C-s (Mail mode): Mail Mode.
-* C-c C-f C-t (Mail mode): Mail Mode.
-* C-c C-h (Outline mode): Outline Visibility.
-* C-c C-i (Outline mode): Outline Visibility.
-* C-c C-j (Term mode): Term Mode.
-* C-c C-k (Picture mode): Rectangles in Picture.
-* C-c C-k (Term mode): Term Mode.
-* C-c C-k (TeX mode): TeX Print.
-* C-c C-l (Calendar mode): General Calendar.
-* C-c C-l (TeX mode): TeX Print.
-* C-c C-n (Fortran mode): Fortran Motion.
-* C-c C-n (Outline mode): Outline Motion.
-* C-c C-o (Shell mode): Shell Mode.
-* C-c C-p (Fortran mode): Fortran Motion.
-* C-c C-p (Outline mode): Outline Motion.
-* C-c C-p (TeX mode): TeX Print.
-* C-c C-q (Mail mode): Mail Mode.
-* C-c C-q (Term mode): Paging in Term.
-* C-c C-q (TeX mode): TeX Print.
-* C-c C-r (Fortran mode): Fortran Columns.
-* C-c C-r (Shell mode): Shell Mode.
-* C-c C-r (TeX mode): TeX Print.
-* C-c C-s (Mail mode): Mail Mode.
-* C-c C-s (Outline mode): Outline Visibility.
-* C-c C-u (Outline mode): Outline Motion.
-* C-c C-u (Shell mode): Shell Mode.
-* C-c C-w (Fortran mode): Fortran Columns.
-* C-c C-w (Mail mode): Mail Mode.
-* C-c C-w (Picture mode): Rectangles in Picture.
-* C-c C-w (Shell mode): Shell Mode.
-* C-c C-x (Picture mode): Rectangles in Picture.
-* C-c C-y (Mail mode): Mail Mode.
-* C-c C-y (Picture mode): Rectangles in Picture.
-* C-c C-y (Shell mode): Shell Mode.
-* C-c C-z (Shell mode): Shell Mode.
-* C-c TAB (Picture mode): Tabs in Picture.
-* C-c { (TeX mode): TeX Editing.
-* C-c } (TeX mode): TeX Editing.
-* C-d: Killing.
-* C-d (Shell mode): Shell Mode.
-* C-e: Basic.
-* C-e (Calendar mode): Move to Beginning or End.
-* C-END: Basic.
-* C-f: Basic.
-* C-f (Calendar mode): Calendar Unit Motion.
-* C-g <1>: Quitting.
-* C-g: Minibuffer.
-* C-g (isearch-mode): Incremental Search.
-* C-h: Key Sequences.
-* C-h a: Help.
-* C-h b: Help.
-* C-h C: Coding Systems.
-* C-h c: Help.
-* C-h C-\: Select Input Method.
-* C-h C-c: Help.
-* C-h C-d: Help.
-* C-h C-w: Help.
-* C-h f <1>: Documentation.
-* C-h f: Help.
-* C-h h: Mule Intro.
-* C-h I: Select Input Method.
-* C-h i: Help.
-* C-h k: Help.
-* C-h L: Language Environments.
-* C-h l: Help.
-* C-h m: Help.
-* C-h n: Help.
-* C-h s: Syntax Change.
-* C-h t <1>: Help.
-* C-h t: Basic.
-* C-h v <1>: Examining.
-* C-h v <2>: Documentation.
-* C-h v: Help.
-* C-h w: Help.
-* C-HOME: Basic.
-* C-k: Killing.
-* C-l <1>: Scrolling.
-* C-l: Basic.
-* C-l (query-replace): Query Replace.
-* C-LEFT: Basic.
-* C-M-@ <1>: Lists.
-* C-M-@: Marking Objects.
-* C-M-\ <1>: Multi-line Indent.
-* C-M-\: Indentation Commands.
-* C-M-a: Defuns.
-* C-M-a (Fortran mode): Fortran Motion.
-* C-M-b: Lists.
-* C-M-c: Recursive Edit.
-* C-M-d: Lists.
-* C-M-e: Defuns.
-* C-M-e (Fortran mode): Fortran Motion.
-* C-M-f: Lists.
-* C-M-h <1>: Defuns.
-* C-M-h: Marking Objects.
-* C-M-h (Fortran mode): Fortran Motion.
-* C-M-k <1>: Lists.
-* C-M-k: Killing.
-* C-M-n: Lists.
-* C-M-o: Indentation Commands.
-* C-M-p: Lists.
-* C-M-q: Multi-line Indent.
-* C-M-q (Fortran mode): ForIndent Commands.
-* C-M-t <1>: Lists.
-* C-M-t: Transpose.
-* C-M-u: Lists.
-* C-M-v <1>: Other Window.
-* C-M-v: Minibuffer Edit.
-* C-M-w: Appending Kills.
-* C-M-x <1>: External Lisp.
-* C-M-x: Lisp Eval.
-* C-n: Basic.
-* C-n (Calendar mode): Calendar Unit Motion.
-* C-o: Blank Lines.
-* C-p: Basic.
-* C-p (Calendar mode): Calendar Unit Motion.
-* C-q: Basic.
-* C-q (isearch-mode): Incremental Search.
-* C-r: Incremental Search.
-* C-r (isearch-mode): Incremental Search.
-* C-r (query-replace): Query Replace.
-* C-RIGHT: Basic.
-* C-s: Incremental Search.
-* C-s (isearch-mode): Incremental Search.
-* C-SPC: Setting Mark.
-* C-SPC (Calendar mode): Mark and Region.
-* C-t <1>: Transpose.
-* C-t: Basic.
-* C-u: Arguments.
-* C-u - C-x ;: Comments.
-* C-u C-@: Mark Ring.
-* C-u C-SPC: Mark Ring.
-* C-u C-x v v: Editing with VC.
-* C-u TAB: Multi-line Indent.
-* C-v <1>: Scrolling.
-* C-v: Basic.
-* C-v (Calendar mode): Scroll Calendar.
-* C-w: Killing.
-* C-w (isearch-mode): Incremental Search.
-* C-w (query-replace): Query Replace.
-* C-x: Key Sequences.
-* C-x $: Selective Display.
-* C-x (: Basic Kbd Macro.
-* C-x ): Basic Kbd Macro.
-* C-x .: Fill Prefix.
-* C-x 0: Change Window.
-* C-x 1: Change Window.
-* C-x 2: Split Window.
-* C-x 3: Split Window.
-* C-x 4: Pop Up Window.
-* C-x 4 .: Find Tag.
-* C-x 4 b: Select Buffer.
-* C-x 4 d: Dired Enter.
-* C-x 4 f: Visiting.
-* C-x 4 m: Sending Mail.
-* C-x 5 b: Select Buffer.
-* C-x 5 C-f: Visiting.
-* C-x ;: Comments.
-* C-x <: Horizontal Scrolling.
-* C-x < (Calendar mode): Scroll Calendar.
-* C-x =: Position Info.
-* C-x >: Horizontal Scrolling.
-* C-x > (Calendar mode): Scroll Calendar.
-* C-x [: Pages.
-* C-x [ (Calendar mode): Calendar Unit Motion.
-* C-x ]: Pages.
-* C-x ] (Calendar mode): Calendar Unit Motion.
-* C-x ^: Change Window.
-* C-x `: Compilation.
-* C-x a g: Defining Abbrevs.
-* C-x a i g: Defining Abbrevs.
-* C-x a i l: Defining Abbrevs.
-* C-x a l: Defining Abbrevs.
-* C-x b: Select Buffer.
-* C-x C-b: List Buffers.
-* C-x C-c: Exiting.
-* C-x C-d: ListDir.
-* C-x C-e: Lisp Eval.
-* C-x C-l: Case.
-* C-x C-o <1>: Killing.
-* C-x C-o: Blank Lines.
-* C-x C-p <1>: Pages.
-* C-x C-p: Marking Objects.
-* C-x C-q: Misc Buffer.
-* C-x C-q (version control): Editing with VC.
-* C-x C-s: Saving.
-* C-x C-t: Transpose.
-* C-x C-u: Case.
-* C-x C-v: Visiting.
-* C-x C-w: Saving.
-* C-x C-x: Setting Mark.
-* C-x C-x (Calendar mode): Mark and Region.
-* C-x d: Dired Enter.
-* C-x DEL <1>: Sentences.
-* C-x DEL <2>: Kill Errors.
-* C-x DEL: Killing.
-* C-x e: Basic Kbd Macro.
-* C-x ESC ESC: Repetition.
-* C-x f: Fill Commands.
-* C-x h: Marking Objects.
-* C-x k: Kill Buffer.
-* C-x l: Pages.
-* C-x m: Sending Mail.
-* C-x n n: Narrowing.
-* C-x n w: Narrowing.
-* C-x o: Other Window.
-* C-x q: Kbd Macro Query.
-* C-x r +: RegNumbers.
-* C-x r b: Bookmarks.
-* C-x r g: RegText.
-* C-x r i: RegText.
-* C-x r j: RegPos.
-* C-x r l: Bookmarks.
-* C-x r m: Bookmarks.
-* C-x r n: RegNumbers.
-* C-x r r: RegRect.
-* C-x r s: RegText.
-* C-x r SPC: RegPos.
-* C-x r w: RegConfig.
-* C-x RET: Mule Intro.
-* C-x RET c: Specify Coding.
-* C-x RET C-\: Select Input Method.
-* C-x RET f: Specify Coding.
-* C-x RET k: Specify Coding.
-* C-x RET p: Specify Coding.
-* C-x RET t: Specify Coding.
-* C-x s: Saving.
-* C-x TAB: Indentation Commands.
-* C-x u: Undo.
-* C-x v =: Old Versions.
-* C-x v a: Change Logs and VC.
-* C-x v c: Editing with VC.
-* C-x v d: VC Status.
-* C-x v h: Version Headers.
-* C-x v i: Editing with VC.
-* C-x v l: VC Status.
-* C-x v r: Making Snapshots.
-* C-x v s: Making Snapshots.
-* C-x v u: Editing with VC.
-* C-x v ~: Old Versions.
-* C-x }: Change Window.
-* C-y: Kill Ring.
-* C-y (isearch-mode): Incremental Search.
-* C-z: Exiting.
-* control key: Intro to Keystrokes.
-* d (Calendar mode): Diary Commands.
-* DEL <1>: Program Modes.
-* DEL <2>: Major Modes.
-* DEL <3>: Kill Errors.
-* DEL <4>: Killing.
-* DEL: Basic.
-* DEL (isearch-mode): Incremental Search.
-* DEL (query-replace): Query Replace.
-* DOWN: Basic.
-* END: Basic.
-* ESC <1>: Meta Key.
-* ESC: Key Sequences.
-* ESC (query-replace): Query Replace.
-* g CHAR (Calendar mode): From Other Calendar.
-* g d (Calendar mode): Specified Dates.
-* g m l (Calendar mode): Mayan Calendar.
-* h (Calendar mode): Holidays.
-* HOME: Basic.
-* hyper key <1>: Super and Hyper Keys.
-* hyper key <2>: Representing Keystrokes.
-* hyper key: Intro to Keystrokes.
-* i a (Calendar mode): Special Diary Entries.
-* i b (Calendar mode): Special Diary Entries.
-* i c (Calendar mode): Special Diary Entries.
-* i d (Calendar mode): Adding to Diary.
-* i m (Calendar mode): Adding to Diary.
-* i w (Calendar mode): Adding to Diary.
-* i y (Calendar mode): Adding to Diary.
-* LEFT: Basic.
-* LFD <1>: Basic Indent.
-* LFD <2>: Major Modes.
-* LFD: String Key Sequences.
-* LFD (TeX mode): TeX Editing.
-* m (Calendar mode): Diary Commands.
-* M (Calendar mode): Lunar Phases.
-* M-!: Single Shell.
-* M-$: Spelling.
-* M-%: Query Replace.
-* M-': Expanding Abbrevs.
-* M-(: Balanced Editing.
-* M-): Balanced Editing.
-* M-,: Tags Search.
-* M--: Arguments.
-* M-- M-c: Fixing Case.
-* M-- M-l: Fixing Case.
-* M-- M-u: Fixing Case.
-* M-.: Find Tag.
-* M-/: Dynamic Abbrevs.
-* M-1: Arguments.
-* M-;: Comments.
-* M-<: Basic.
-* M-< (Calendar mode): Move to Beginning or End.
-* M-=: Position Info.
-* M-= (Calendar mode): Mark and Region.
-* M->: Basic.
-* M-> (Calendar mode): Move to Beginning or End.
-* M-?: Nroff Mode.
-* M-@ <1>: Words.
-* M-@: Marking Objects.
-* M-[: Paragraphs.
-* M-\ <1>: Indentation Commands.
-* M-\: Killing.
-* M-]: Paragraphs.
-* M-^ <1>: Indentation Commands.
-* M-^: Killing.
-* M-a: Sentences.
-* M-a (Calendar mode): Move to Beginning or End.
-* M-b: Words.
-* M-c: Case.
-* M-C-s: Regexp Search.
-* M-d <1>: Words.
-* M-d: Killing.
-* M-DEL <1>: Words.
-* M-DEL <2>: Kill Errors.
-* M-DEL: Killing.
-* M-e: Sentences.
-* M-e (Calendar mode): Move to Beginning or End.
-* M-ESC: Lisp Eval.
-* M-f: Words.
-* M-g: Fill Commands.
-* M-h <1>: Paragraphs.
-* M-h: Marking Objects.
-* M-i: Tab Stops.
-* M-k <1>: Sentences.
-* M-k: Killing.
-* M-l: Case.
-* M-LFD: Comments.
-* M-LFD (Fortran mode): ForIndent Commands.
-* M-m: Indentation Commands.
-* M-n <1>: Nroff Mode.
-* M-n: Repetition.
-* M-n (isearch-mode): Incremental Search.
-* M-n (minibuffer history): Minibuffer History.
-* M-n (Shell mode): Shell Mode.
-* M-p <1>: Nroff Mode.
-* M-p: Repetition.
-* M-p (isearch-mode): Incremental Search.
-* M-p (minibuffer history): Minibuffer History.
-* M-p (Shell mode): Shell Mode.
-* M-q: Fill Commands.
-* M-r: Basic.
-* M-r (minibuffer history): Minibuffer History.
-* M-s: Fill Commands.
-* M-s (minibuffer history): Minibuffer History.
-* M-SPC: Killing.
-* M-t <1>: Words.
-* M-t: Transpose.
-* M-TAB <1>: Tabs in Picture.
-* M-TAB: Lisp Completion.
-* M-TAB (customization buffer): Changing an Option.
-* M-TAB (isearch-mode): Incremental Search.
-* M-u: Case.
-* M-v <1>: Scrolling.
-* M-v: Basic.
-* M-v (Calendar mode): Scroll Calendar.
-* M-w: Kill Ring.
-* M-x: M-x.
-* M-y: Earlier Kills.
-* M-z: Killing.
-* M-{ (Calendar mode): Calendar Unit Motion.
-* M-|: Single Shell.
-* M-} (Calendar mode): Calendar Unit Motion.
-* M-~: Saving.
-* META: Meta Key.
-* meta key: Intro to Keystrokes.
-* next: Scrolling.
-* o (Calendar mode): Specified Dates.
-* p (Calendar mode): To Other Calendar.
-* p d (Calendar mode): General Calendar.
-* pgdn: Scrolling.
-* PGDN: Basic.
-* pgup: Scrolling.
-* PGUP: Basic.
-* prior: Scrolling.
-* q (Calendar mode): General Calendar.
-* RET: Basic.
-* RET (isearch-mode): Incremental Search.
-* RET (Shell mode): Shell Mode.
-* RIGHT: Basic.
-* s (Calendar mode): Diary Commands.
-* S (Calendar mode): Sunrise/Sunset.
-* S-TAB (customization buffer): Changing an Option.
-* shift key: Intro to Keystrokes.
-* SPC: Completion Commands.
-* SPC (Calendar mode): General Calendar.
-* SPC (query-replace): Query Replace.
-* super key <1>: Super and Hyper Keys.
-* super key <2>: Representing Keystrokes.
-* super key: Intro to Keystrokes.
-* t (Calendar mode): LaTeX Calendar.
-* TAB <1>: Basic Indent.
-* TAB <2>: Text Mode.
-* TAB <3>: Indentation.
-* TAB <4>: Major Modes.
-* TAB <5>: Completion Example.
-* TAB: String Key Sequences.
-* TAB (customization buffer): Changing an Option.
-* TAB (Shell mode): Shell Mode.
-* u (Calendar mode) <1>: Diary Commands.
-* u (Calendar mode): Holidays.
-* UP: Basic.
-* x (Calendar mode): Holidays.
+File: xemacs.info, Node: Glossary, Next: Manifesto, Prev: Intro, Up: Top
+
+Glossary
+********
+
+Abbrev
+ An abbrev is a text string which expands into a different text
+ string when present in the buffer. For example, you might define
+ a short word as an abbrev for a long phrase that you want to insert
+ frequently. *Note Abbrevs::.
+
+Aborting
+ Aborting means getting out of a recursive edit (q.v.). You can use
+ the commands `C-]' and `M-x top-level' for this. *Note Quitting::.
+
+Auto Fill mode
+ Auto Fill mode is a minor mode in which text you insert is
+ automatically broken into lines of fixed width. *Note Filling::.
+
+Auto Saving
+ Auto saving means that Emacs automatically stores the contents of
+ an Emacs buffer in a specially-named file so the information will
+ not be lost if the buffer is lost due to a system error or user
+ error. *Note Auto Save::.
+
+Backup File
+ A backup file records the contents that a file had before the
+ current editing session. Emacs creates backup files automatically
+ to help you track down or cancel changes you later regret. *Note
+ Backup::.
+
+Balance Parentheses
+ Emacs can balance parentheses manually or automatically. Manual
+ balancing is done by the commands to move over balanced expressions
+ (*note Lists::). Automatic balancing is done by blinking the
+ parenthesis that matches one just inserted (*note Matching Parens:
+ Matching.).
+
+Bind
+ To bind a key is to change its binding (q.v.). *Note Rebinding::.
+
+Binding
+ A key gets its meaning in Emacs by having a binding which is a
+ command (q.v.), a Lisp function that is run when the key is typed.
+ *Note Binding: Commands. Customization often involves rebinding a
+ character to a different command function. The bindings of all
+ keys are recorded in the keymaps (q.v.). *Note Keymaps::.
+
+Blank Lines
+ Blank lines are lines that contain only whitespace. Emacs has
+ several commands for operating on the blank lines in a buffer.
+
+Buffer
+ The buffer is the basic editing unit; one buffer corresponds to one
+ piece of text being edited. You can have several buffers, but at
+ any time you are editing only one, the `selected' buffer, though
+ several buffers can be visible when you are using multiple
+ windows. *Note Buffers::.
+
+Buffer Selection History
+ Emacs keeps a buffer selection history which records how recently
+ each Emacs buffer was selected. Emacs uses this list when
+ choosing a buffer to select. *Note Buffers::.
+
+C-
+ `C' in the name of a character is an abbreviation for Control.
+ *Note C-: Keystrokes.
+
+C-M-
+ `C-M-' in the name of a character is an abbreviation for
+ Control-Meta. *Note C-M-: Keystrokes.
+
+Case Conversion
+ Case conversion means changing text from upper case to lower case
+ or vice versa. *Note Case::, for the commands for case conversion.
+
+Characters
+ Characters form the contents of an Emacs buffer; also, Emacs
+ commands are invoked by keys (q.v.), which are sequences of one or
+ more characters. *Note Keystrokes::.
+
+Command
+ A command is a Lisp function specially defined to be able to serve
+ as a key binding in Emacs. When you type a key (q.v.), Emacs
+ looks up its binding (q.v.) in the relevant keymaps (q.v.) to find
+ the command to run. *Note Commands::.
+
+Command Name
+ A command name is the name of a Lisp symbol which is a command
+ (*note Commands::). You can invoke any command by its name using
+ `M-x' (*note M-x::).
+
+Comments
+ A comment is text in a program which is intended only for the
+ people reading the program, and is marked specially so that it
+ will be ignored when the program is loaded or compiled. Emacs
+ offers special commands for creating, aligning, and killing
+ comments. *Note Comments::.
+
+Compilation
+ Compilation is the process of creating an executable program from
+ source code. Emacs has commands for compiling files of Emacs Lisp
+ code (*note Lisp Libraries::) and programs in C and other languages
+ (*note Compilation::).
+
+Complete Key
+ A complete key is a character or sequence of characters which,
+ when typed by the user, fully specifies one action to be performed
+ by Emacs. For example, `X' and `Control-f' and `Control-x m' are
+ keys. Keys derive their meanings from being bound (q.v.) to
+ commands (q.v.). Thus, `X' is conventionally bound to a command
+ to insert `X' in the buffer; `C-x m' is conventionally bound to a
+ command to begin composing a mail message. *Note Keystrokes::.
+
+Completion
+ When Emacs automatically fills an abbreviation for a name into the
+ entire name, that process is called completion. Completion is
+ done for minibuffer (q.v.) arguments when the set of possible
+ valid inputs is known; for example, on command names, buffer
+ names, and file names. Completion occurs when you type <TAB>,
+ <SPC>, or <RET>. *Note Completion::.
+
+Continuation Line
+ When a line of text is longer than the width of the frame, it
+ takes up more than one screen line when displayed. We say that the
+ text line is continued, and all screen lines used for it after the
+ first are called continuation lines. *Note Continuation: Basic.
+
+Control-Character
+ ASCII characters with octal codes 0 through 037, and also code
+ 0177, do not have graphic images assigned to them. These are the
+ control characters. Any control character can be typed by holding
+ down the <CTRL> key and typing some other character; some have
+ special keys on the keyboard. <RET>, <TAB>, <ESC>, <LFD>, and
+ <DEL> are all control characters. *Note Keystrokes::.
+
+Copyleft
+ A copyleft is a notice giving the public legal permission to
+ redistribute a program or other work of art. Copylefts are used
+ by leftists to enrich the public just as copyrights are used by
+ rightists to gain power over the public.
+
+Current Buffer
+ The current buffer in Emacs is the Emacs buffer on which most
+ editing commands operate. You can select any Emacs buffer as the
+ current one. *Note Buffers::.
+
+Current Line
+ The line point is on (*note Point::).
+
+Current Paragraph
+ The paragraph that point is in. If point is between paragraphs,
+ the current paragraph is the one that follows point. *Note
+ Paragraphs::.
+
+Current Defun
+ The defun (q.v.) that point is in. If point is between defuns, the
+ current defun is the one that follows point. *Note Defuns::.
+
+Cursor
+ The cursor is the rectangle on the screen which indicates the
+ position called point (q.v.) at which insertion and deletion takes
+ place. The cursor is on or under the character that follows
+ point. Often people speak of `the cursor' when, strictly
+ speaking, they mean `point'. *Note Cursor: Basic.
+
+Customization
+ Customization is making minor changes in the way Emacs works. It
+ is often done by setting variables (*note Variables::) or by
+ rebinding keys (*note Keymaps::).
+
+Default Argument
+ The default for an argument is the value that is used if you do not
+ specify one. When Emacs prompts you in the minibuffer for an
+ argument, the default argument is used if you just type <RET>.
+ *Note Minibuffer::.
+
+Default Directory
+ When you specify a file name that does not start with `/' or `~',
+ it is interpreted relative to the current buffer's default
+ directory. *Note Default Directory: Minibuffer File.
+
+Defun
+ A defun is a list at the top level of parenthesis or bracket
+ structure in a program. It is so named because most such lists in
+ Lisp programs are calls to the Lisp function `defun'. *Note
+ Defuns::.
+
+<DEL>
+ The <DEL> character runs the command that deletes one character of
+ text. *Note DEL: Basic.
+
+Deletion
+ Deleting text means erasing it without saving it. Emacs deletes
+ text only when it is expected not to be worth saving (all
+ whitespace, or only one character). The alternative is killing
+ (q.v.). *Note Deletion: Killing.
+
+Deletion of Files
+ Deleting a file means removing it from the file system. *Note
+ Misc File Ops::.
+
+Deletion of Messages
+ Deleting a message means flagging it to be eliminated from your
+ mail file. Until the mail file is expunged, you can undo this by
+ undeleting the message.
+
+Deletion of Frames
+ When working under the multi-frame X-based version of XEmacs, you
+ can delete individual frames using the Close menu item from the
+ File menu.
+
+Deletion of Windows
+ When you delete a subwindow of an Emacs frame, you eliminate it
+ from the frame. Other windows expand to use up the space. The
+ deleted window can never come back, but no actual text is lost.
+ *Note Windows::.
+
+Directory
+ Files in the Unix file system are grouped into file directories.
+ *Note Directories: ListDir.
+
+Dired
+ Dired is the Emacs facility that displays the contents of a file
+ directory and allows you to "edit the directory", performing
+ operations on the files in the directory. *Note Dired::.
+
+Disabled Command
+ A disabled command is one that you may not run without special
+ confirmation. Commands are usually disabled because they are
+ confusing for beginning users. *Note Disabling::.
+
+Dribble File
+ A file into which Emacs writes all the characters that the user
+ types on the keyboard. Dribble files are used to make a record for
+ debugging Emacs bugs. Emacs does not make a dribble file unless
+ you tell it to. *Note Bugs::.
+
+Echo Area
+ The area at the bottom of the Emacs frame which is used for
+ echoing the arguments to commands, for asking questions, and for
+ printing brief messages (including error messages). *Note Echo
+ Area::.
+
+Echoing
+ Echoing refers to acknowledging the receipt of commands by
+ displaying them (in the echo area). Emacs never echoes
+ single-character keys; longer keys echo only if you pause while
+ typing them.
+
+Error
+ An error occurs when an Emacs command cannot execute in the current
+ circumstances. When an error occurs, execution of the command
+ stops (unless the command has been programmed to do otherwise) and
+ Emacs reports the error by printing an error message (q.v.).
+ Type-ahead is discarded. Then Emacs is ready to read another
+ editing command.
+
+Error Messages
+ Error messages are single lines of output printed by Emacs when the
+ user asks for something impossible to do (such as killing text
+ forward when point is at the end of the buffer). They appear in
+ the echo area, accompanied by a beep.
+
+<ESC>
+ <ESC> is a character used as a prefix for typing Meta characters on
+ keyboards lacking a <META> key. Unlike the <META> key (which,
+ like the <SHIFT> key, is held down while another character is
+ typed), the <ESC> key is pressed and released, and applies to the
+ next character typed.
+
+Fill Prefix
+ The fill prefix is a string that Emacs enters at the beginning of
+ each line when it performs filling. It is not regarded as part of
+ the text to be filled. *Note Filling::.
+
+Filling
+ Filling text means moving text from line to line so that all the
+ lines are approximately the same length. *Note Filling::.
+
+Frame
+ When running Emacs on a TTY terminal, "frame" means the terminal's
+ screen. When running Emacs under X, you can have multiple frames,
+ each corresponding to a top-level X window and each looking like
+ the screen on a TTY. Each frame contains one or more
+ non-overlapping Emacs windows (possibly with associated
+ scrollbars, under X), an echo area, and (under X) possibly a
+ menubar, toolbar, and/or gutter.
+
+Global
+ Global means `independent of the current environment; in effect
+ throughout Emacs'. It is the opposite of local (q.v.). Examples
+ of the use of `global' appear below.
+
+Global Abbrev
+ A global definition of an abbrev (q.v.) is effective in all major
+ modes that do not have local (q.v.) definitions for the same
+ abbrev. *Note Abbrevs::.
+
+Global Keymap
+ The global keymap (q.v.) contains key bindings that are in effect
+ unless local key bindings in a major mode's local keymap (q.v.)
+ override them.*Note Keymaps::.
+
+Global Substitution
+ Global substitution means replacing each occurrence of one string
+ by another string through a large amount of text. *Note Replace::.
+
+Global Variable
+ The global value of a variable (q.v.) takes effect in all buffers
+ that do not have their own local (q.v.) values for the variable.
+ *Note Variables::.
+
+Graphic Character
+ Graphic characters are those assigned pictorial images rather than
+ just names. All the non-Meta (q.v.) characters except for the
+ Control (q.v.) character are graphic characters. These include
+ letters, digits, punctuation, and spaces; they do not include
+ <RET> or <ESC>. In Emacs, typing a graphic character inserts that
+ character (in ordinary editing modes). *Note Basic Editing: Basic.
+
+Grinding
+ Grinding means adjusting the indentation in a program to fit the
+ nesting structure. *Note Grinding: Indentation.
+
+Hardcopy
+ Hardcopy means printed output. Emacs has commands for making
+ printed listings of text in Emacs buffers. *Note Hardcopy::.
+
+<HELP>
+ You can type <HELP> at any time to ask what options you have, or
+ to ask what any command does. <HELP> is really `Control-h'.
+ *Note Help::.
+
+Inbox
+ An inbox is a file in which mail is delivered by the operating
+ system. Some mail handlers transfers mail from inboxes to mail
+ files (q.v.) in which the mail is then stored permanently or until
+ explicitly deleted.
+
+Indentation
+ Indentation means blank space at the beginning of a line. Most
+ programming languages have conventions for using indentation to
+ illuminate the structure of the program, and Emacs has special
+ features to help you set up the correct indentation. *Note
+ Indentation::.
+
+Insertion
+ Insertion means copying text into the buffer, either from the
+ keyboard or from some other place in Emacs.
+
+Justification
+ Justification means adding extra spaces to lines of text to make
+ them come exactly to a specified width. *Note Justification:
+ Filling.
+
+Keyboard Macros
+ Keyboard macros are a way of defining new Emacs commands from
+ sequences of existing ones, with no need to write a Lisp program.
+ *Note Keyboard Macros::.
+
+Key
+ A key is a sequence of characters that, when input to Emacs,
+ specify or begin to specify a single action for Emacs to perform.
+ That is, the sequence is considered a single unit. If the key is
+ enough to specify one action, it is a complete key (q.v.); if it
+ is less than enough, it is a prefix key (q.v.). *Note
+ Keystrokes::.
+
+Keymap
+ The keymap is the data structure that records the bindings (q.v.)
+ of keys to the commands that they run. For example, the keymap
+ binds the character `C-n' to the command function `next-line'.
+ *Note Keymaps::.
+
+Kill Ring
+ The kill ring is the place where all text you have killed recently
+ is saved. You can re-insert any of the killed text still in the
+ ring; this is called yanking (q.v.). *Note Yanking::.
+
+Killing
+ Killing means erasing text and saving it on the kill ring so it
+ can be yanked (q.v.) later. Some other systems call this
+ "cutting." Most Emacs commands to erase text do killing, as
+ opposed to deletion (q.v.). *Note Killing::.
+
+Killing Jobs
+ Killing a job (such as, an invocation of Emacs) means making it
+ cease to exist. Any data within it, if not saved in a file, is
+ lost. *Note Exiting::.
+
+List
+ A list is, approximately, a text string beginning with an open
+ parenthesis and ending with the matching close parenthesis. In C
+ mode and other non-Lisp modes, groupings surrounded by other kinds
+ of matched delimiters appropriate to the language, such as braces,
+ are also considered lists. Emacs has special commands for many
+ operations on lists. *Note Lists::.
+
+Local
+ Local means `in effect only in a particular context'; the relevant
+ kind of context is a particular function execution, a particular
+ buffer, or a particular major mode. Local is the opposite of
+ `global' (q.v.). Specific uses of `local' in Emacs terminology
+ appear below.
+
+Local Abbrev
+ A local abbrev definition is effective only if a particular major
+ mode is selected. In that major mode, it overrides any global
+ definition for the same abbrev. *Note Abbrevs::.
+
+Local Keymap
+ A local keymap is used in a particular major mode; the key bindings
+ (q.v.) in the current local keymap override global bindings of the
+ same keys. *Note Keymaps::.
+
+Local Variable
+ A local value of a variable (q.v.) applies to only one buffer.
+ *Note Locals::.
+
+M-
+ `M-' in the name of a character is an abbreviation for <META>, one
+ of the modifier keys that can accompany any character. *Note
+ Keystrokes::.
+
+M-C-
+ `M-C-' in the name of a character is an abbreviation for
+ Control-Meta; it means the same thing as `C-M-'. If your terminal
+ lacks a real <META> key, you type a Control-Meta character by
+ typing <ESC> and then typing the corresponding Control character.
+ *Note C-M-: Keystrokes.
+
+M-x
+ `M-x' is the key which is used to call an Emacs command by name.
+ You use it to call commands that are not bound to keys. *Note
+ M-x::.
+
+Mail
+ Mail means messages sent from one user to another through the
+ computer system, to be read at the recipient's convenience. Emacs
+ has commands for composing and sending mail, and for reading and
+ editing the mail you have received. *Note Sending Mail::.
+
+Major Mode
+ The major modes are a mutually exclusive set of options each of
+ which configures Emacs for editing a certain sort of text.
+ Ideally, each programming language has its own major mode. *Note
+ Major Modes::.
+
+Mark
+ The mark points to a position in the text. It specifies one end
+ of the region (q.v.), point being the other end. Many commands
+ operate on the whole region, that is, all the text from point to
+ the mark. *Note Mark::.
+
+Mark Ring
+ The mark ring is used to hold several recent previous locations of
+ the mark, just in case you want to move back to them. *Note Mark
+ Ring::.
+
+Message
+ See `mail'.
+
+Meta
+ Meta is the name of a modifier bit which a command character may
+ have. It is present in a character if the character is typed with
+ the <META> key held down. Such characters are given names that
+ start with `Meta-'. For example, `Meta-<' is typed by holding down
+ <META> and at the same time typing `<' (which itself is done, on
+ most terminals, by holding down <SHIFT> and typing `,'). *Note
+ Meta: Keystrokes.
+
+Meta Character
+ A Meta character is one whose character code includes the Meta bit.
+
+Minibuffer
+ The minibuffer is the window that Emacs displays inside the echo
+ area (q.v.) when it prompts you for arguments to commands. *Note
+ Minibuffer::.
+
+Minor Mode
+ A minor mode is an optional feature of Emacs which can be switched
+ on or off independent of the major mode. Each minor mode has a
+ command to turn it on or off. *Note Minor Modes::.
+
+Mode Line
+ The mode line is the line at the bottom of each text window (q.v.),
+ which gives status information on the buffer displayed in that
+ window. *Note Mode Line::.
+
+Modified Buffer
+ A buffer (q.v.) is modified if its text has been changed since the
+ last time the buffer was saved (or since it was created, if it has
+ never been saved). *Note Saving::.
+
+Moving Text
+ Moving text means erasing it from one place and inserting it in
+ another. This is done by killing (q.v.) and then yanking (q.v.).
+ *Note Killing::.
+
+Named Mark
+ A named mark is a register (q.v.) in its role of recording a
+ location in text so that you can move point to that location.
+ *Note Registers::.
+
+Narrowing
+ Narrowing means creating a restriction (q.v.) that limits editing
+ in the current buffer to only a part of the text in the buffer.
+ Text outside that part is inaccessible to the user until the
+ boundaries are widened again, but it is still there, and saving
+ the file saves the invisible text. *Note Narrowing::.
+
+Newline
+ <LFD> characters in the buffer terminate lines of text and are
+ called newlines. *Note Newline: Keystrokes.
+
+Numeric Argument
+ A numeric argument is a number, specified before a command, to
+ change the effect of the command. Often the numeric argument
+ serves as a repeat count. *Note Arguments::.
+
+Option
+ An option is a variable (q.v.) that allows you to customize Emacs
+ by giving it a new value. *Note Variables::.
+
+Overwrite Mode
+ Overwrite mode is a minor mode. When it is enabled, ordinary text
+ characters replace the existing text after point rather than
+ pushing it to the right. *Note Minor Modes::.
+
+Page
+ A page is a unit of text, delimited by formfeed characters (ASCII
+ Control-L, code 014) coming at the beginning of a line. Some Emacs
+ commands are provided for moving over and operating on pages.
+ *Note Pages::.
+
+Paragraphs
+ Paragraphs are the medium-size unit of English text. There are
+ special Emacs commands for moving over and operating on paragraphs.
+ *Note Paragraphs::.
+
+Parsing
+ We say that Emacs parses words or expressions in the text being
+ edited. Really, all it knows how to do is find the other end of a
+ word or expression. *Note Syntax::.
+
+Point
+ Point is the place in the buffer at which insertion and deletion
+ occur. Point is considered to be between two characters, not at
+ one character. The terminal's cursor (q.v.) indicates the
+ location of point. *Note Point: Basic.
+
+Prefix Key
+ A prefix key is a key (q.v.) whose sole function is to introduce a
+ set of multi-character keys. `Control-x' is an example of a prefix
+ key; any two-character sequence starting with `C-x' is also a
+ legitimate key. *Note Keystrokes::.
+
+Prompt
+ A prompt is text printed to ask the user for input. Printing a
+ prompt is called prompting. Emacs prompts always appear in the
+ echo area (q.v.). One kind of prompting happens when the
+ minibuffer is used to read an argument (*note Minibuffer::); the
+ echoing which happens when you pause in the middle of typing a
+ multi-character key is also a kind of prompting (*note Echo
+ Area::).
+
+Quitting
+ Quitting means cancelling a partially typed command or a running
+ command, using `C-g'. *Note Quitting::.
+
+Quoting
+ Quoting means depriving a character of its usual special
+ significance. In Emacs this is usually done with `Control-q'.
+ What constitutes special significance depends on the context and
+ on convention. For example, an "ordinary" character as an Emacs
+ command inserts itself; so in this context, a special character is
+ any character that does not normally insert itself (such as <DEL>,
+ for example), and quoting it makes it insert itself as if it were
+ not special. Not all contexts allow quoting. *Note Quoting:
+ Basic.
+
+Read-only Buffer
+ A read-only buffer is one whose text you are not allowed to change.
+ Normally Emacs makes buffers read-only when they contain text which
+ has a special significance to Emacs, such asDired buffers.
+ Visiting a file that is write-protected also makes a read-only
+ buffer. *Note Buffers::.
+
+Recursive Editing Level
+ A recursive editing level is a state in which part of the
+ execution of a command involves asking the user to edit some text.
+ This text may or may not be the same as the text to which the
+ command was applied. The mode line indicates recursive editing
+ levels with square brackets (`[' and `]'). *Note Recursive Edit::.
+
+Redisplay
+ Redisplay is the process of correcting the image on the screen to
+ correspond to changes that have been made in the text being edited.
+ *Note Redisplay: Frame.
+
+Regexp
+ See `regular expression'.
+
+Region
+ The region is the text between point (q.v.) and the mark (q.v.).
+ Many commands operate on the text of the region. *Note Region:
+ Mark.
+
+Registers
+ Registers are named slots in which text or buffer positions or
+ rectangles can be saved for later use. *Note Registers::.
+
+Regular Expression
+ A regular expression is a pattern that can match various text
+ strings; for example, `l[0-9]+' matches `l' followed by one or more
+ digits. *Note Regexps::.
+
+Replacement
+ See `global substitution'.
+
+Restriction
+ A buffer's restriction is the amount of text, at the beginning or
+ the end of the buffer, that is temporarily invisible and
+ inaccessible. Giving a buffer a nonzero amount of restriction is
+ called narrowing (q.v.). *Note Narrowing::.
+
+<RET>
+ <RET> is the character than runs the command to insert a newline
+ into the text. It is also used to terminate most arguments read
+ in the minibuffer (q.v.). *Note Return: Keystrokes.
+
+Saving
+ Saving a buffer means copying its text into the file that was
+ visited (q.v.) in that buffer. To actually change a file you have
+ edited in Emacs, you have to save it. *Note Saving::.
+
+Scrolling
+ Scrolling means shifting the text in the Emacs window to make a
+ different part ot the buffer visible. *Note Scrolling: Display.
+
+Searching
+ Searching means moving point to the next occurrence of a specified
+ string. *Note Search::.
+
+Selecting
+ Selecting a buffer means making it the current (q.v.) buffer.
+ *Note Selecting: Buffers.
+
+Self-documentation
+ Self-documentation is the feature of Emacs which can tell you what
+ any command does, or can give you a list of all commands related
+ to a topic you specify. You ask for self-documentation with the
+ help character, `C-h'. *Note Help::.
+
+Sentences
+ Emacs has commands for moving by or killing by sentences. *Note
+ Sentences::.
+
+Sexp
+ An sexp (short for `s-expression,' itself short for `symbolic
+ expression') is the basic syntactic unit of Lisp in its textual
+ form: either a list, or Lisp atom. Many Emacs commands operate on
+ sexps. The term `sexp' is generalized to languages other than
+ Lisp to mean a syntactically recognizable expression. *Note
+ Sexps: Lists.
+
+Simultaneous Editing
+ Simultaneous editing means two users modifying the same file at
+ once. If simultaneous editing is not detected, you may lose your
+ work. Emacs detects all cases of simultaneous editing and warns
+ the user to investigate them. *Note Simultaneous Editing:
+ Interlocking.
+
+String
+ A string is a kind of Lisp data object which contains a sequence of
+ characters. Many Emacs variables are intended to have strings as
+ values. The Lisp syntax for a string consists of the characters in
+ the string with a `"' before and another `"' after. Write a `"'
+ that is part of the string as `\"' and a `\' that is part of the
+ string as `\\'. You can include all other characters, including
+ newline, just by writing them inside the string. You can also
+ include escape sequences as in C, such as `\n' for newline or
+ `\241' using an octal character code.
+
+String Substitution
+ See `global substitution'.
+
+Syntax Table
+ The syntax table tells Emacs which characters are part of a word,
+ which characters balance each other like parentheses, etc. *Note
+ Syntax::.
+
+Tag Table
+ A tag table is a file that serves as an index to the function
+ definitions in one or more other files. *Note Tags::.
+
+Termscript File
+ A termscript file contains a record of all characters Emacs sent to
+ the terminal. It is used for tracking down bugs in Emacs
+ redisplay. Emacs does not make a termscript file unless
+ explicitly instructed to do so. *Note Bugs::.
+
+Text
+ Text has two meanings (*note Text::):
+
+ * Data consisting of a sequence of characters, as opposed to
+ binary numbers, images, graphics commands, executable
+ programs, and the like. The contents of an Emacs buffer are
+ always text in this sense.
+
+ * Data consisting of written human language, as opposed to
+ programs, or something that follows the stylistic conventions
+ of human language.
+
+Top Level
+ Top level is the normal state of Emacs, in which you are editing
+ the text of the file you have visited. You are at top level
+ whenever you are not in a recursive editing level (q.v.) or the
+ minibuffer (q.v.), and not in the middle of a command. You can
+ get back to top level by aborting (q.v.) and quitting (q.v.).
+ *Note Quitting::.
+
+Transposition
+ Transposing two units of text means putting each one into the place
+ formerly occupied by the other. There are Emacs commands to
+ transpose two adjacent characters, words, sexps (q.v.), or lines
+ (*note Transpose::).
+
+Truncation
+ Truncating text lines in the display means leaving out any text on
+ a line that does not fit within the right margin of the window
+ displaying it. See also `continuation line'. *Note Truncation:
+ Basic.
+
+Undoing
+ Undoing means making your previous editing go in reverse, bringing
+ back the text that existed earlier in the editing session. *Note
+ Undo::.
+
+Variable
+ A variable is Lisp object that can store an arbitrary value.
+ Emacs uses some variables for internal purposes, and has others
+ (known as `options' (q.v.)) you can set to control the behavior of
+ Emacs. The variables used in Emacs that you are likely to be
+ interested in are listed in the Variables Index of this manual.
+ *Note Variables::, for information on variables.
+
+Visiting
+ Visiting a file means loading its contents into a buffer (q.v.)
+ where they can be edited. *Note Visiting::.
+
+Whitespace
+ Whitespace is any run of consecutive formatting characters (spaces,
+ tabs, newlines, and backspaces).
+
+Widening
+ Widening is removing any restriction (q.v.) on the current buffer;
+ it is the opposite of narrowing (q.v.). *Note Narrowing::.
+
+Window
+ Emacs divides the frame into one or more windows, each of which can
+ display the contents of one buffer (q.v.) at any time. *Note
+ Frame::, for basic information on how Emacs uses the frame. *Note
+ Windows::, for commands to control the use of windows. Note that if
+ you are running Emacs under X, terminology can be confusing: Each
+ Emacs frame occupies a separate X window and can, in turn, be
+ divided into different subwindows.
+
+Word Abbrev
+ Synonymous with `abbrev'.
+
+Word Search
+ Word search is searching for a sequence of words, considering the
+ punctuation between them as insignificant. *Note Word Search::.
+
+Yanking
+ Yanking means reinserting text previously killed. It can be used
+ to undo a mistaken kill, or for copying or moving text. Some other
+ systems call this "pasting". *Note Yanking::.
translation approved by the author instead of in the original English.
\1f
-File: xemacs.info, Node: Command Index, Next: Variable Index, Prev: Key Index, Up: Top
+File: xemacs.info, Node: Manifesto, Next: Key Index, Prev: Glossary, Up: Top
-Command and Function Index
-**************************
+The GNU Manifesto
+*****************
+
+What's GNU? GNU's Not Unix!
+============================
+
+ GNU, which stands for GNU's Not Unix, is the name for the complete
+Unix-compatible software system which I am writing so that I can give it
+away free to everyone who can use it. Several other volunteers are
+helping me. Contributions of time, money, programs, and equipment are
+greatly needed.
+
+ So far we have an Emacs text editor with Lisp for writing editor
+commands, a source level debugger, a yacc-compatible parser generator,
+a linker, and around 35 utilities. A shell (command interpreter) is
+nearly completed. A new portable optimizing C compiler has compiled
+itself and may be released this year. An initial kernel exists, but
+many more features are needed to emulate Unix. When the kernel and
+compiler are finished, it will be possible to distribute a GNU system
+suitable for program development. We will use TeX as our text
+formatter, but an nroff is being worked on. We will use the free,
+portable X window system as well. After this we will add a portable
+Common Lisp, an Empire game, a spreadsheet, and hundreds of other
+things, plus online documentation. We hope to supply, eventually,
+everything useful that normally comes with a Unix system, and more.
+
+ GNU will be able to run Unix programs, but will not be identical to
+Unix. We will make all improvements that are convenient, based on our
+experience with other operating systems. In particular, we plan to
+have longer filenames, file version numbers, a crashproof file system,
+filename completion perhaps, terminal-independent display support, and
+perhaps eventually a Lisp-based window system through which several
+Lisp programs and ordinary Unix programs can share a screen. Both C
+and Lisp will be available as system programming languages. We will
+try to support UUCP, MIT Chaosnet, and Internet protocols for
+communication.
+
+ GNU is aimed initially at machines in the 68000/16000 class with
+virtual memory, because they are the easiest machines to make it run
+on. The extra effort to make it run on smaller machines will be left
+to someone who wants to use it on them.
+
+ To avoid horrible confusion, please pronounce the `G' in the word
+`GNU' when it is the name of this project.
+
+Why I Must Write GNU
+====================
+
+ I consider that the golden rule requires that if I like a program I
+must share it with other people who like it. Software sellers want to
+divide the users and conquer them, making each user agree not to share
+with others. I refuse to break solidarity with other users in this
+way. I cannot in good conscience sign a nondisclosure agreement or a
+software license agreement. For years I worked within the Artificial
+Intelligence Lab to resist such tendencies and other inhospitalities,
+but eventually they had gone too far: I could not remain in an
+institution where such things are done for me against my will.
+
+ So that I can continue to use computers without dishonor, I have
+decided to put together a sufficient body of free software so that I
+will be able to get along without any software that is not free. I
+have resigned from the AI lab to deny MIT any legal excuse to prevent
+me from giving GNU away.
+
+Why GNU Will Be Compatible With Unix
+====================================
+
+ Unix is not my ideal system, but it is not too bad. The essential
+features of Unix seem to be good ones, and I think I can fill in what
+Unix lacks without spoiling them. And a system compatible with Unix
+would be convenient for many other people to adopt.
+
+How GNU Will Be Available
+=========================
+
+ GNU is not in the public domain. Everyone will be permitted to
+modify and redistribute GNU, but no distributor will be allowed to
+restrict its further redistribution. That is to say, proprietary
+modifications will not be allowed. I want to make sure that all
+versions of GNU remain free.
+
+Why Many Other Programmers Want to Help
+=======================================
+
+ I have found many other programmers who are excited about GNU and
+want to help.
+
+ Many programmers are unhappy about the commercialization of system
+software. It may enable them to make more money, but it requires them
+to feel in conflict with other programmers in general rather than feel
+as comrades. The fundamental act of friendship among programmers is the
+sharing of programs; marketing arrangements now typically used
+essentially forbid programmers to treat others as friends. The
+purchaser of software must choose between friendship and obeying the
+law. Naturally, many decide that friendship is more important. But
+those who believe in law often do not feel at ease with either choice.
+They become cynical and think that programming is just a way of making
+money.
+
+ By working on and using GNU rather than proprietary programs, we can
+be hospitable to everyone and obey the law. In addition, GNU serves as
+an example to inspire and a banner to rally others to join us in
+sharing. This can give us a feeling of harmony which is impossible if
+we use software that is not free. For about half the programmers I
+talk to, this is an important happiness that money cannot replace.
+
+How You Can Contribute
+======================
+
+ I am asking computer manufacturers for donations of machines and
+money. I'm asking individuals for donations of programs and work.
+
+ One consequence you can expect if you donate machines is that GNU
+will run on them at an early date. The machines should be complete,
+ready-to-use systems, approved for use in a residential area, and not
+in need of sophisticated cooling or power.
+
+ I have found very many programmers eager to contribute part-time
+work for GNU. For most projects, such part-time distributed work would
+be very hard to coordinate; the independently-written parts would not
+work together. But for the particular task of replacing Unix, this
+problem is absent. A complete Unix system contains hundreds of utility
+programs, each of which is documented separately. Most interface
+specifications are fixed by Unix compatibility. If each contributor
+can write a compatible replacement for a single Unix utility, and make
+it work properly in place of the original on a Unix system, then these
+utilities will work right when put together. Even allowing for Murphy
+to create a few unexpected problems, assembling these components will
+be a feasible task. (The kernel will require closer communication and
+will be worked on by a small, tight group.)
+
+ If I get donations of money, I may be able to hire a few people full
+or part time. The salary won't be high by programmers' standards, but
+I'm looking for people for whom building community spirit is as
+important as making money. I view this as a way of enabling dedicated
+people to devote their full energies to working on GNU by sparing them
+the need to make a living in another way.
+
+Why All Computer Users Will Benefit
+===================================
+
+ Once GNU is written, everyone will be able to obtain good system
+software free, just like air.
+
+ This means much more than just saving everyone the price of a Unix
+license. It means that much wasteful duplication of system programming
+effort will be avoided. This effort can go instead into advancing the
+state of the art.
+
+ Complete system sources will be available to everyone. As a result,
+a user who needs changes in the system will always be free to make them
+himself, or hire any available programmer or company to make them for
+him. Users will no longer be at the mercy of one programmer or company
+which owns the sources and is in sole position to make changes.
+
+ Schools will be able to provide a much more educational environment
+by encouraging all students to study and improve the system code.
+Harvard's computer lab used to have the policy that no program could be
+installed on the system if its sources were not on public display, and
+upheld it by actually refusing to install certain programs. I was very
+much inspired by this.
+
+ Finally, the overhead of considering who owns the system software
+and what one is or is not entitled to do with it will be lifted.
+
+ Arrangements to make people pay for using a program, including
+licensing of copies, always incur a tremendous cost to society through
+the cumbersome mechanisms necessary to figure out how much (that is,
+which programs) a person must pay for. And only a police state can
+force everyone to obey them. Consider a space station where air must
+be manufactured at great cost: charging each breather per liter of air
+may be fair, but wearing the metered gas mask all day and all night is
+intolerable even if everyone can afford to pay the air bill. And the
+TV cameras everywhere to see if you ever take the mask off are
+outrageous. It's better to support the air plant with a head tax and
+chuck the masks.
+
+ Copying all or parts of a program is as natural to a programmer as
+breathing, and as productive. It ought to be as free.
+
+Some Easily Rebutted Objections to GNU's Goals
+==============================================
+
+ "Nobody will use it if it is free, because that means they can't
+ rely on any support."
+
+ "You have to charge for the program to pay for providing the
+ support."
+
+ If people would rather pay for GNU plus service than get GNU free
+without service, a company to provide just service to people who have
+obtained GNU free ought to be profitable.
+
+ We must distinguish between support in the form of real programming
+work and mere handholding. The former is something one cannot rely on
+from a software vendor. If your problem is not shared by enough
+people, the vendor will tell you to get lost.
+
+ If your business needs to be able to rely on support, the only way
+is to have all the necessary sources and tools. Then you can hire any
+available person to fix your problem; you are not at the mercy of any
+individual. With Unix, the price of sources puts this out of
+consideration for most businesses. With GNU this will be easy. It is
+still possible for there to be no available competent person, but this
+problem cannot be blamed on distibution arrangements. GNU does not
+eliminate all the world's problems, only some of them.
+
+ Meanwhile, the users who know nothing about computers need
+handholding: doing things for them which they could easily do
+themselves but don't know how.
+
+ Such services could be provided by companies that sell just
+hand-holding and repair service. If it is true that users would rather
+spend money and get a product with service, they will also be willing
+to buy the service having got the product free. The service companies
+will compete in quality and price; users will not be tied to any
+particular one. Meanwhile, those of us who don't need the service
+should be able to use the program without paying for the service.
+
+ "You cannot reach many people without advertising, and you must
+ charge for the program to support that."
+
+ "It's no use advertising a program people can get free."
+
+ There are various forms of free or very cheap publicity that can be
+used to inform numbers of computer users about something like GNU. But
+it may be true that one can reach more microcomputer users with
+advertising. If this is really so, a business which advertises the
+service of copying and mailing GNU for a fee ought to be successful
+enough to pay for its advertising and more. This way, only the users
+who benefit from the advertising pay for it.
+
+ On the other hand, if many people get GNU from their friends, and
+such companies don't succeed, this will show that advertising was not
+really necessary to spread GNU. Why is it that free market advocates
+don't want to let the free market decide this?
+
+ "My company needs a proprietary operating system to get a
+ competitive edge."
+
+ GNU will remove operating system software from the realm of
+competition. You will not be able to get an edge in this area, but
+neither will your competitors be able to get an edge over you. You and
+they will compete in other areas, while benefitting mutually in this
+one. If your business is selling an operating system, you will not
+like GNU, but that's tough on you. If your business is something else,
+GNU can save you from being pushed into the expensive business of
+selling operating systems.
+
+ I would like to see GNU development supported by gifts from many
+manufacturers and users, reducing the cost to each.
+
+ "Don't programmers deserve a reward for their creativity?"
+
+ If anything deserves a reward, it is social contribution.
+Creativity can be a social contribution, but only in so far as society
+is free to use the results. If programmers deserve to be rewarded for
+creating innovative programs, by the same token they deserve to be
+punished if they restrict the use of these programs.
+
+ "Shouldn't a programmer be able to ask for a reward for his
+ creativity?"
+
+ There is nothing wrong with wanting pay for work, or seeking to
+maximize one's income, as long as one does not use means that are
+destructive. But the means customary in the field of software today
+are based on destruction.
+
+ Extracting money from users of a program by restricting their use of
+it is destructive because the restrictions reduce the amount and the
+ways that the program can be used. This reduces the amount of wealth
+that humanity derives from the program. When there is a deliberate
+choice to restrict, the harmful consequences are deliberate destruction.
+
+ The reason a good citizen does not use such destructive means to
+become wealthier is that, if everyone did so, we would all become
+poorer from the mutual destructiveness. This is Kantian ethics; or,
+the Golden Rule. Since I do not like the consequences that result if
+everyone hoards information, I am required to consider it wrong for one
+to do so. Specifically, the desire to be rewarded for one's creativity
+does not justify depriving the world in general of all or part of that
+creativity.
+
+ "Won't programmers starve?"
+
+ I could answer that nobody is forced to be a programmer. Most of us
+cannot manage to get any money for standing on the street and making
+faces. But we are not, as a result, condemned to spend our lives
+standing on the street making faces, and starving. We do something
+else.
+
+ But that is the wrong answer because it accepts the questioner's
+implicit assumption: that without ownership of software, programmers
+cannot possibly be paid a cent. Supposedly it is all or nothing.
+
+ The real reason programmers will not starve is that it will still be
+possible for them to get paid for programming; just not paid as much as
+now.
+
+ Restricting copying is not the only basis for business in software.
+It is the most common basis because it brings in the most money. If it
+were prohibited, or rejected by the customer, software business would
+move to other bases of organization which are now used less often.
+There are always numerous ways to organize any kind of business.
+
+ Probably programming will not be as lucrative on the new basis as it
+is now. But that is not an argument against the change. It is not
+considered an injustice that sales clerks make the salaries that they
+now do. If programmers made the same, that would not be an injustice
+either. (In practice they would still make considerably more than
+that.)
+
+ "Don't people have a right to control how their creativity is
+ used?"
+
+ "Control over the use of one's ideas" really constitutes control over
+other people's lives; and it is usually used to make their lives more
+difficult.
+
+ People who have studied the issue of intellectual property rights
+carefully (such as lawyers) say that there is no intrinsic right to
+intellectual property. The kinds of supposed intellectual property
+rights that the government recognizes were created by specific acts of
+legislation for specific purposes.
+
+ For example, the patent system was established to encourage
+inventors to disclose the details of their inventions. Its purpose was
+to help society rather than to help inventors. At the time, the life
+span of 17 years for a patent was short compared with the rate of
+advance of the state of the art. Since patents are an issue only among
+manufacturers, for whom the cost and effort of a license agreement are
+small compared with setting up production, the patents often do not do
+much harm. They do not obstruct most individuals who use patented
+products.
+
+ The idea of copyright did not exist in ancient times, when authors
+frequently copied other authors at length in works of non-fiction. This
+practice was useful, and is the only way many authors' works have
+survived even in part. The copyright system was created expressly for
+the purpose of encouraging authorship. In the domain for which it was
+invented--books, which could be copied economically only on a printing
+press--it did little harm, and did not obstruct most of the individuals
+who read the books.
+
+ All intellectual property rights are just licenses granted by society
+because it was thought, rightly or wrongly, that society as a whole
+would benefit by granting them. But in any particular situation, we
+have to ask: are we really better off granting such license? What kind
+of act are we licensing a person to do?
+
+ The case of programs today is very different from that of books a
+hundred years ago. The fact that the easiest way to copy a program is
+from one neighbor to another, the fact that a program has both source
+code and object code which are distinct, and the fact that a program is
+used rather than read and enjoyed, combine to create a situation in
+which a person who enforces a copyright is harming society as a whole
+both materially and spiritually; in which a person should not do so
+regardless of whether the law enables him to.
+
+ "Competition makes things get done better."
+
+ The paradigm of competition is a race: by rewarding the winner, we
+encourage everyone to run faster. When capitalism really works this
+way, it does a good job; but its defenders are wrong in assuming it
+always works this way. If the runners forget why the reward is offered
+and become intent on winning, no matter how, they may find other
+strategies--such as, attacking other runners. If the runners get into
+a fist fight, they will all finish late.
+
+ Proprietary and secret software is the moral equivalent of runners
+in a fist fight. Sad to say, the only referee we've got does not seem
+to object to fights; he just regulates them ("For every ten yards you
+run, you can fire one shot"). He really ought to break them up, and
+penalize runners for even trying to fight.
+
+ "Won't everyone stop programming without a monetary incentive?"
+
+ Actually, many people will program with absolutely no monetary
+incentive. Programming has an irresistible fascination for some
+people, usually the people who are best at it. There is no shortage of
+professional musicians who keep at it even though they have no hope of
+making a living that way.
+
+ But really this question, though commonly asked, is not appropriate
+to the situation. Pay for programmers will not disappear, only become
+less. So the right question is, will anyone program with a reduced
+monetary incentive? My experience shows that they will.
+
+ For more than ten years, many of the world's best programmers worked
+at the Artificial Intelligence Lab for far less money than they could
+have had anywhere else. They got many kinds of non-monetary rewards:
+fame and appreciation, for example. And creativity is also fun, a
+reward in itself.
+
+ Then most of them left when offered a chance to do the same
+interesting work for a lot of money.
+
+ What the facts show is that people will program for reasons other
+than riches; but if given a chance to make a lot of money as well, they
+will come to expect and demand it. Low-paying organizations do poorly
+in competition with high-paying ones, but they do not have to do badly
+if the high-paying ones are banned.
+
+ "We need the programmers desperately. If they demand that we stop
+ helping our neighbors, we have to obey."
+
+ You're never so desperate that you have to obey this sort of demand.
+Remember: millions for defense, but not a cent for tribute!
+
+ "Programmers need to make a living somehow."
+
+ In the short run, this is true. However, there are plenty of ways
+that programmers could make a living without selling the right to use a
+program. This way is customary now because it brings programmers and
+businessmen the most money, not because it is the only way to make a
+living. It is easy to find other ways if you want to find them. Here
+are a number of examples.
+
+ A manufacturer introducing a new computer will pay for the porting of
+operating systems onto the new hardware.
+
+ The sale of teaching, hand-holding, and maintenance services could
+also employ programmers.
+
+ People with new ideas could distribute programs as freeware and ask
+for donations from satisfied users or sell hand-holding services. I
+have met people who are already working this way successfully.
+
+ Users with related needs can form users' groups and pay dues. A
+group would contract with programming companies to write programs that
+the group's members would like to use.
+
+ All sorts of development can be funded with a Software Tax:
+
+ Suppose everyone who buys a computer has to pay a certain percent
+ of the price as a software tax. The government gives this to an
+ agency like the NSF to spend on software development.
+
+ But if the computer buyer makes a donation to software development
+ himself, he can take a credit against the tax. He can donate to
+ the project of his own choosing--often, chosen because he hopes to
+ use the results when
+
+ it is done. He can take a credit for any amount of donation up to
+ the total tax he had to pay.
+
+ The total tax rate could be decided by a vote of the payers of the
+ tax, weighted according to the amount they will be taxed on.
+
+ The consequences:
+
+ * The computer-using community supports software development.
+
+ * This community decides what level of support is needed.
+
+ * Users who care which projects their share is spent on can
+ choose this for themselves.
+
+ In the long run, making programs free is a step toward the
+post-scarcity world, where nobody will have to work very hard just to
+make a living. People will be free to devote themselves to activities
+that are fun, such as programming, after spending the necessary ten
+hours a week on required tasks such as legislation, family counseling,
+robot repair, and asteroid prospecting. There will be no need to be
+able to make a living from programming.
+
+ We have already greatly reduced the amount of work that the whole
+society must do for its actual productivity, but only a little of this
+has translated itself into leisure for workers because much
+nonproductive activity is required to accompany productive activity.
+The main causes of this are bureaucracy and isometric struggles against
+competition. Free software will greatly reduce these drains in the
+area of software production. We must do this, in order for technical
+gains in productivity to translate into less work for us.
+
+\1f
+File: xemacs.info, Node: Key Index, Next: Command Index, Prev: Manifesto, Up: Top
+
+Key (Character) Index
+*********************
* Menu:
-* abbrev-mode <1>: Minor Modes.
-* abbrev-mode: Abbrevs.
-* abbrev-prefix-mark: Expanding Abbrevs.
-* abort-recursive-edit <1>: Quitting.
-* abort-recursive-edit: Recursive Edit.
-* add-change-log-entry: Change Log.
-* add-global-abbrev: Defining Abbrevs.
-* add-menu: Menu Customization.
-* add-menu-item: Menu Customization.
-* add-mode-abbrev: Defining Abbrevs.
-* add-name-to-file: Misc File Ops.
-* american-calendar: Date Formats.
-* append-next-kill: Appending Kills.
-* append-to-buffer: Accumulating Text.
-* append-to-file <1>: Misc File Ops.
-* append-to-file: Accumulating Text.
-* apropos: Help.
-* ask-user-about-lock: Interlocking.
-* auto-fill-mode <1>: Minor Modes.
-* auto-fill-mode: Auto Fill.
-* auto-save-mode: Auto Save Control.
-* back-to-indentation: Indentation Commands.
-* backward-char: Basic.
-* backward-delete-char-untabify: Program Modes.
-* backward-kill-sentence <1>: Sentences.
-* backward-kill-sentence <2>: Kill Errors.
-* backward-kill-sentence: Killing.
-* backward-kill-word <1>: Words.
-* backward-kill-word <2>: Kill Errors.
-* backward-kill-word: Killing.
-* backward-list: Lists.
-* backward-page: Pages.
-* backward-paragraph: Paragraphs.
-* backward-sentence: Sentences.
-* backward-sexp: Lists.
-* backward-text-line: Nroff Mode.
-* backward-up-list: Lists.
-* backward-word: Words.
-* batch-byte-compile: Compiling Libraries.
-* beginning-of-buffer: Basic.
-* beginning-of-defun: Defuns.
-* beginning-of-fortran-subprogram: Fortran Motion.
-* beginning-of-line: Basic.
-* bookmark-delete: Bookmarks.
-* bookmark-insert: Bookmarks.
-* bookmark-insert-location: Bookmarks.
-* bookmark-jump: Bookmarks.
-* bookmark-load: Bookmarks.
-* bookmark-save: Bookmarks.
-* bookmark-set: Bookmarks.
-* bookmark-write: Bookmarks.
-* buffer-menu: Several Buffers.
-* byte-compile-and-load-file: Compiling Libraries.
-* byte-compile-buffer: Compiling Libraries.
-* byte-compile-file: Compiling Libraries.
-* byte-recompile-directory: Compiling Libraries.
-* c-indent-line: Basic Indent.
-* calendar: Calendar/Diary.
-* calendar-backward-day: Calendar Unit Motion.
-* calendar-backward-month: Calendar Unit Motion.
-* calendar-backward-week: Calendar Unit Motion.
-* calendar-beginning-of-month: Move to Beginning or End.
-* calendar-beginning-of-week: Move to Beginning or End.
-* calendar-beginning-of-year: Move to Beginning or End.
-* calendar-count-days-region: Mark and Region.
-* calendar-cursor-holidays: Holidays.
-* calendar-end-of-month: Move to Beginning or End.
-* calendar-end-of-week: Move to Beginning or End.
-* calendar-end-of-year: Move to Beginning or End.
-* calendar-exchange-point-and-mark: Mark and Region.
-* calendar-forward-day: Calendar Unit Motion.
-* calendar-forward-month: Calendar Unit Motion.
-* calendar-forward-week: Calendar Unit Motion.
-* calendar-forward-year: Calendar Unit Motion.
-* calendar-goto-astro-day-number: From Other Calendar.
-* calendar-goto-chinese-date: From Other Calendar.
-* calendar-goto-coptic-date: From Other Calendar.
-* calendar-goto-date: Specified Dates.
-* calendar-goto-ethiopic-date: From Other Calendar.
-* calendar-goto-french-date: From Other Calendar.
-* calendar-goto-hebrew-date: From Other Calendar.
-* calendar-goto-islamic-date: From Other Calendar.
-* calendar-goto-iso-date: From Other Calendar.
-* calendar-goto-julian-date: From Other Calendar.
-* calendar-goto-mayan-long-count-date: Mayan Calendar.
-* calendar-goto-persian-date: From Other Calendar.
-* calendar-goto-today: Specified Dates.
-* calendar-mark-today: Calendar Customizing.
-* calendar-next-calendar-round-date: Mayan Calendar.
-* calendar-next-haab-date: Mayan Calendar.
-* calendar-next-tzolkin-date: Mayan Calendar.
-* calendar-other-month: Specified Dates.
-* calendar-phases-of-moon: Lunar Phases.
-* calendar-previous-haab-date: Mayan Calendar.
-* calendar-previous-tzolkin-date: Mayan Calendar.
-* calendar-print-astro-day-number: To Other Calendar.
-* calendar-print-chinese-date: To Other Calendar.
-* calendar-print-coptic-date: To Other Calendar.
-* calendar-print-day-of-year: General Calendar.
-* calendar-print-ethiopic-date: To Other Calendar.
-* calendar-print-french-date: To Other Calendar.
-* calendar-print-hebrew-date: To Other Calendar.
-* calendar-print-islamic-date: To Other Calendar.
-* calendar-print-iso-date: To Other Calendar.
-* calendar-print-julian-date: To Other Calendar.
-* calendar-print-mayan-date: To Other Calendar.
-* calendar-print-persian-date: To Other Calendar.
-* calendar-set-mark: Mark and Region.
-* calendar-star-date: Calendar Customizing.
-* calendar-sunrise-sunset: Sunrise/Sunset.
-* calendar-unmark <1>: Diary Commands.
-* calendar-unmark: Holidays.
-* call-last-kbd-macro: Basic Kbd Macro.
-* cancel-debug-on-entry: Lisp Debug.
-* capitalize-word <1>: Case.
-* capitalize-word: Fixing Case.
-* center-line: Fill Commands.
-* choose-completion: Completion Commands.
-* clear-rectangle: Rectangles.
-* comint-delchar-or-maybe-eof: Shell Mode.
-* comint-dynamic-complete: Shell Mode.
-* comint-next-input: Shell Mode.
-* comint-previous-input: Shell Mode.
-* command-apropos: Help.
-* compare-windows <1>: Other Window.
-* compare-windows: Comparing Files.
-* compile: Compilation.
-* compile-defun: Defuns.
-* convert-mocklisp-buffer: Mocklisp.
-* conx: CONX.
-* conx-buffer: CONX.
-* conx-init: CONX.
-* conx-load: CONX.
-* conx-region: CONX.
-* conx-save: CONX.
-* copy-file: Misc File Ops.
-* copy-last-shell-input: Shell Mode.
-* copy-rectangle-to-register: RegRect.
-* copy-region-as-kill: Kill Ring.
-* copy-to-buffer: Accumulating Text.
-* copy-to-register: RegText.
-* count-lines-page: Pages.
-* count-lines-region: Position Info.
-* count-matches: Other Repeating Search.
-* count-text-lines: Nroff Mode.
-* customize: Easy Customization.
-* customize-apropos: Specific Customization.
-* customize-browse: Customization Groups.
-* customize-customized: Specific Customization.
-* customize-face: Specific Customization.
-* customize-group: Specific Customization.
-* customize-option: Specific Customization.
-* customize-saved: Specific Customization.
-* dabbrev-expand: Dynamic Abbrevs.
-* debug: Lisp Debug.
-* debug-on-entry: Lisp Debug.
-* default-value: Locals.
-* define-abbrevs: Saving Abbrevs.
-* define-key <1>: Programmatic Rebinding.
-* define-key: Interactive Rebinding.
-* delete-backward-char <1>: Kill Errors.
-* delete-backward-char <2>: Killing.
-* delete-backward-char: Basic.
-* delete-blank-lines <1>: Killing.
-* delete-blank-lines: Blank Lines.
-* delete-char <1>: Basic Picture.
-* delete-char: Killing.
-* delete-file: Misc File Ops.
-* delete-horizontal-space <1>: Indentation Commands.
-* delete-horizontal-space: Killing.
-* delete-indentation <1>: Indentation Commands.
-* delete-indentation: Killing.
-* delete-matching-lines: Other Repeating Search.
-* delete-menu-item: Menu Customization.
-* delete-non-matching-lines: Other Repeating Search.
-* delete-other-windows: Change Window.
-* delete-rectangle: Rectangles.
-* delete-window: Change Window.
-* describe-bindings: Help.
-* describe-calendar-mode: General Calendar.
-* describe-coding-system: Coding Systems.
-* describe-copying: Help.
-* describe-distribution: Help.
-* describe-function <1>: Documentation.
-* describe-function: Help.
-* describe-input-method: Select Input Method.
-* describe-key: Help.
-* describe-key-briefly: Help.
-* describe-language-environment: Language Environments.
-* describe-mode: Help.
-* describe-no-warranty: Help.
-* describe-syntax: Syntax Change.
-* describe-variable <1>: Examining.
-* describe-variable <2>: Documentation.
-* describe-variable: Help.
-* diary: Diary Commands.
-* diary-anniversary <1>: Sexp Diary Entries.
-* diary-anniversary: Special Diary Entries.
-* diary-astro-day-number: Sexp Diary Entries.
-* diary-block: Special Diary Entries.
-* diary-cyclic <1>: Sexp Diary Entries.
-* diary-cyclic: Special Diary Entries.
-* diary-day-of-year: Sexp Diary Entries.
-* diary-float: Special Diary Entries.
-* diary-french-date: Sexp Diary Entries.
-* diary-hebrew-date: Sexp Diary Entries.
-* diary-islamic-date: Sexp Diary Entries.
-* diary-iso-date: Sexp Diary Entries.
-* diary-julian-date: Sexp Diary Entries.
-* diary-mail-entries: Diary Commands.
-* diary-mayan-date: Sexp Diary Entries.
-* diary-omer: Sexp Diary Entries.
-* diary-parasha: Sexp Diary Entries.
-* diary-phases-of-moon: Sexp Diary Entries.
-* diary-rosh-hodesh: Sexp Diary Entries.
-* diary-sabbath-candles: Sexp Diary Entries.
-* diary-sunrise-sunset: Sexp Diary Entries.
-* diary-yahrzeit: Sexp Diary Entries.
-* diff: Comparing Files.
-* diff-backup: Comparing Files.
-* digit-argument: Arguments.
-* dired: Dired Enter.
-* dired-other-window <1>: Pop Up Window.
-* dired-other-window: Dired Enter.
-* disable-command: Disabling.
-* disable-menu-item: Menu Customization.
-* disassemble: Compiling Libraries.
-* display-time: Mode Line.
-* dissociated-press: Dissociated Press.
-* do-auto-save: Auto Save Control.
-* doctor: Total Frustration.
-* down-list: Lists.
-* downcase-region: Case.
-* downcase-word <1>: Case.
-* downcase-word: Fixing Case.
-* edit-abbrevs: Editing Abbrevs.
-* edit-abbrevs-redefine: Editing Abbrevs.
-* edit-options: Edit Options.
-* edit-picture: Picture.
-* edit-tab-stops <1>: Text Mode.
-* edit-tab-stops: Tab Stops.
-* edit-tab-stops-note-changes: Tab Stops.
-* edt-emulation-off: Emulation.
-* edt-emulation-on: Emulation.
-* electric-nroff-mode: Nroff Mode.
-* emacs-lisp-mode: Lisp Eval.
-* emacs-version: Bugs.
-* enable-command: Disabling.
-* enable-menu-item: Menu Customization.
-* end-kbd-macro: Basic Kbd Macro.
-* end-of-buffer: Basic.
-* end-of-defun: Defuns.
-* end-of-fortran-subprogram: Fortran Motion.
-* end-of-line: Basic.
-* enlarge-window: Change Window.
-* enlarge-window-horizontally: Change Window.
-* european-calendar: Date Formats.
-* eval-current-buffer: Lisp Eval.
-* eval-defun: Lisp Eval.
-* eval-expression: Lisp Eval.
-* eval-last-sexp: Lisp Eval.
-* eval-region: Lisp Eval.
-* exchange-point-and-mark: Setting Mark.
-* execute-extended-command: M-x.
-* exit-calendar: General Calendar.
-* exit-recursive-edit: Recursive Edit.
-* expand-abbrev: Expanding Abbrevs.
-* expand-region-abbrevs: Expanding Abbrevs.
-* fancy-diary-display: Fancy Diary Display.
-* fill-individual-paragraphs: Fill Prefix.
-* fill-paragraph: Fill Commands.
-* fill-region: Fill Commands.
-* fill-region-as-paragraph: Fill Commands.
-* find-alternate-file: Visiting.
-* find-file: Visiting.
-* find-file-other-frame <1>: Visiting.
-* find-file-other-frame: XEmacs under X.
-* find-file-other-window <1>: Pop Up Window.
-* find-file-other-window: Visiting.
-* find-tag: Find Tag.
-* find-tag-other-window <1>: Find Tag.
-* find-tag-other-window: Pop Up Window.
-* find-this-file: Visiting.
-* find-this-file-other-window: Visiting.
-* fortran-column-ruler: Fortran Columns.
-* fortran-comment-region: Fortran Comments.
-* fortran-indent-line: ForIndent Commands.
-* fortran-indent-subprogram: ForIndent Commands.
-* fortran-mode: Fortran.
-* fortran-next-statement: Fortran Motion.
-* fortran-previous-statement: Fortran Motion.
-* fortran-split-line: ForIndent Commands.
-* fortran-window-create: Fortran Columns.
-* forward-char: Basic.
-* forward-list: Lists.
-* forward-page: Pages.
-* forward-paragraph: Paragraphs.
-* forward-sentence: Sentences.
-* forward-sexp: Lists.
-* forward-text-line: Nroff Mode.
-* forward-word: Words.
-* frame-configuration-to-register: RegConfig.
-* global-set-key <1>: Programmatic Rebinding.
-* global-set-key: Interactive Rebinding.
-* goto-char: Basic.
-* goto-line: Basic.
-* hanoi: Amusements.
-* help-with-tutorial <1>: Help.
-* help-with-tutorial: Basic.
-* hide-body: Outline Visibility.
-* hide-entry: Outline Visibility.
-* hide-leaves: Outline Visibility.
-* hide-subtree: Outline Visibility.
-* holidays: Holidays.
-* include-other-diary-files: Included Diary Files.
-* increment-register: RegNumbers.
-* indent-c-exp: Multi-line Indent.
-* indent-for-comment: Comments.
-* indent-new-comment-line: Comments.
-* indent-region <1>: Multi-line Indent.
-* indent-region: Indentation Commands.
-* indent-relative: Indentation Commands.
-* indent-rigidly: Indentation Commands.
-* indent-sexp: Multi-line Indent.
-* indented-text-mode: Text Mode.
-* info: Help.
-* insert-abbrevs: Saving Abbrevs.
-* insert-anniversary-diary-entry: Special Diary Entries.
-* insert-block-diary-entry: Special Diary Entries.
-* insert-cyclic-diary-entry: Special Diary Entries.
-* insert-diary-entry: Adding to Diary.
-* insert-file: Misc File Ops.
-* insert-hebrew-diary-entry: Hebrew/Islamic Entries.
-* insert-islamic-diary-entry: Hebrew/Islamic Entries.
-* insert-kbd-macro: Save Kbd Macro.
-* insert-monthly-diary-entry: Adding to Diary.
-* insert-monthly-hebrew-diary-entry: Hebrew/Islamic Entries.
-* insert-monthly-islamic-diary-entry: Hebrew/Islamic Entries.
-* insert-parentheses: Balanced Editing.
-* insert-register: RegText.
-* insert-weekly-diary-entry: Adding to Diary.
-* insert-yearly-diary-entry: Adding to Diary.
-* insert-yearly-hebrew-diary-entry: Hebrew/Islamic Entries.
-* insert-yearly-islamic-diary-entry: Hebrew/Islamic Entries.
-* interactive: M-x.
-* interrupt-shell-subjob: Shell Mode.
-* inverse-add-global-abbrev: Defining Abbrevs.
-* inverse-add-mode-abbrev: Defining Abbrevs.
-* invert-face: Faces.
-* isearch-abort: Incremental Search.
-* isearch-backward: Incremental Search.
-* isearch-backward-regexp: Regexp Search.
-* isearch-complete: Incremental Search.
-* isearch-delete-char: Incremental Search.
-* isearch-exit: Incremental Search.
-* isearch-forward: Incremental Search.
-* isearch-forward-regexp: Regexp Search.
-* isearch-quote-char: Incremental Search.
-* isearch-repeat-backward: Incremental Search.
-* isearch-repeat-forward: Incremental Search.
-* isearch-ring-advance: Incremental Search.
-* isearch-ring-retreat: Incremental Search.
-* isearch-yank-line: Incremental Search.
-* isearch-yank-word: Incremental Search.
-* jump-to-register <1>: Split Window.
-* jump-to-register: RegPos.
-* just-one-space: Killing.
-* kbd-macro-query: Kbd Macro Query.
-* kill-all-abbrevs: Defining Abbrevs.
-* kill-buffer: Kill Buffer.
-* kill-comment: Comments.
-* kill-compilation: Compilation.
-* kill-line: Killing.
-* kill-local-variable: Locals.
-* kill-output-from-shell: Shell Mode.
-* kill-rectangle: Rectangles.
-* kill-region: Killing.
-* kill-sentence <1>: Sentences.
-* kill-sentence: Killing.
-* kill-sexp <1>: Lists.
-* kill-sexp: Killing.
-* kill-some-buffers: Kill Buffer.
-* kill-word <1>: Words.
-* kill-word: Killing.
-* latex-mode: TeX Mode.
-* LaTeX-mode: TeX Mode.
-* lisp-complete-symbol: Lisp Completion.
-* lisp-indent-line: Basic Indent.
-* lisp-interaction-mode: Lisp Interaction.
-* lisp-mode: External Lisp.
-* lisp-send-defun: External Lisp.
-* list-abbrevs: Editing Abbrevs.
-* list-bookmarks: Bookmarks.
-* list-buffers: List Buffers.
-* list-calendar-holidays: Holidays.
-* list-coding-systems: Coding Systems.
-* list-command-history: Repetition.
-* list-directory: ListDir.
-* list-hebrew-diary-entries: Hebrew/Islamic Entries.
-* list-holidays: Holidays.
-* list-input-methods: Select Input Method.
-* list-islamic-diary-entries: Hebrew/Islamic Entries.
-* list-matching-lines: Other Repeating Search.
-* list-options: Edit Options.
-* list-tags: List Tags.
-* list-yahrzeit-dates: From Other Calendar.
-* load: Loading.
-* load-default-sounds: Audible Bell.
-* load-file: Loading.
-* load-library <1>: Loading.
-* load-library: Startup Paths.
-* load-sound-file: Audible Bell.
-* local-set-key: Interactive Rebinding.
-* local-unset-key: Interactive Rebinding.
-* locate-library: Loading.
-* lpr-buffer: Hardcopy.
-* lpr-region: Hardcopy.
-* mail: Sending Mail.
-* mail-cc: Mail Mode.
-* mail-fill-yanked-message: Mail Mode.
-* mail-interactive-insert-alias: Mail Headers.
-* mail-other-window <1>: Sending Mail.
-* mail-other-window: Pop Up Window.
-* mail-send: Mail Mode.
-* mail-send-and-exit: Mail Mode.
-* mail-signature: Mail Mode.
-* mail-subject: Mail Mode.
-* mail-to: Mail Mode.
-* mail-yank-original: Mail Mode.
-* make-directory: File Names.
-* make-face-bold: Faces.
-* make-face-bold-italic: Faces.
-* make-face-italic: Faces.
-* make-face-larger: Faces.
-* make-face-smaller: Faces.
-* make-face-unbold: Faces.
-* make-face-unitalic: Faces.
-* make-frame: XEmacs under X.
-* make-local-variable: Locals.
-* make-obsolete: Compiling Libraries.
-* make-symbolic-link: Misc File Ops.
-* make-variable-buffer-local: Locals.
-* manual-entry: Documentation.
-* mark-beginning-of-buffer: Setting Mark.
-* mark-calendar-holidays: Holidays.
-* mark-defun <1>: Defuns.
-* mark-defun: Marking Objects.
-* mark-diary-entries: Diary Commands.
-* mark-end-of-buffer: Setting Mark.
-* mark-fortran-subprogram: Fortran Motion.
-* mark-hebrew-diary-entries: Hebrew/Islamic Entries.
-* mark-included-diary-files: Included Diary Files.
-* mark-islamic-diary-entries: Hebrew/Islamic Entries.
-* mark-page <1>: Pages.
-* mark-page: Marking Objects.
-* mark-paragraph <1>: Paragraphs.
-* mark-paragraph: Marking Objects.
-* mark-sexp <1>: Lists.
-* mark-sexp: Marking Objects.
-* mark-whole-buffer: Marking Objects.
-* mark-word <1>: Words.
-* mark-word: Marking Objects.
-* minibuffer-complete: Completion Example.
-* minibuffer-complete-word: Completion Commands.
-* modify-syntax-entry: Syntax Change.
-* mouse-choose-completion: Completion Commands.
-* mouse-del-char: Additional Mouse Operations.
-* mouse-delete-window: Additional Mouse Operations.
-* mouse-keep-one-window: Additional Mouse Operations.
-* mouse-kill-line: Additional Mouse Operations.
-* mouse-line-length: Additional Mouse Operations.
-* mouse-scroll: Additional Mouse Operations.
-* mouse-select: Additional Mouse Operations.
-* mouse-select-and-split: Additional Mouse Operations.
-* mouse-set-mark: Additional Mouse Operations.
-* mouse-set-point: Additional Mouse Operations.
-* mouse-track: Additional Mouse Operations.
-* mouse-track-adjust: Additional Mouse Operations.
-* mouse-track-and-copy-to-cutbuffer: Additional Mouse Operations.
-* mouse-track-delete-and-insert: Additional Mouse Operations.
-* move-over-close-and-reindent: Balanced Editing.
-* move-to-window-line: Basic.
-* name-last-kbd-macro: Save Kbd Macro.
-* narrow-to-region: Narrowing.
-* negative-argument: Arguments.
-* newline: Basic.
-* newline-and-indent: Basic Indent.
-* next-complex-command: Repetition.
-* next-error: Compilation.
-* next-history-element: Minibuffer History.
-* next-line: Basic.
-* next-list-mode-item: Completion Commands.
-* next-matching-history-element: Minibuffer History.
-* not-modified: Saving.
-* nroff-mode: Nroff Mode.
-* number-to-register: RegNumbers.
-* occur: Other Repeating Search.
-* open-dribble-file: Bugs.
-* open-line: Blank Lines.
-* open-rectangle: Rectangles.
-* open-termscript: Bugs.
-* other-window: Other Window.
-* other-window-any-frame: Other Window.
-* outline-backward-same-level: Outline Motion.
-* outline-forward-same-level: Outline Motion.
-* outline-next-visible-heading: Outline Motion.
-* outline-previous-visible-heading: Outline Motion.
-* outline-up-heading: Outline Motion.
-* overwrite-mode: Minor Modes.
-* phases-of-moon: Lunar Phases.
-* picture-backward-clear-column: Basic Picture.
-* picture-backward-column: Basic Picture.
-* picture-clear-column: Basic Picture.
-* picture-clear-line: Basic Picture.
-* picture-clear-rectangle: Rectangles in Picture.
-* picture-clear-rectangle-to-register: Rectangles in Picture.
-* picture-forward-column: Basic Picture.
-* picture-motion: Insert in Picture.
-* picture-motion-reverse: Insert in Picture.
-* picture-move-down: Basic Picture.
-* picture-move-up: Basic Picture.
-* picture-movement-down: Insert in Picture.
-* picture-movement-left: Insert in Picture.
-* picture-movement-ne: Insert in Picture.
-* picture-movement-nw: Insert in Picture.
-* picture-movement-right: Insert in Picture.
-* picture-movement-se: Insert in Picture.
-* picture-movement-sw: Insert in Picture.
-* picture-movement-up: Insert in Picture.
-* picture-newline: Basic Picture.
-* picture-open-line: Basic Picture.
-* picture-set-tab-stops: Tabs in Picture.
-* picture-tab: Tabs in Picture.
-* picture-tab-search: Tabs in Picture.
-* picture-yank-rectangle: Rectangles in Picture.
-* picture-yank-rectangle-from-register: Rectangles in Picture.
-* plain-TeX-mode: TeX Mode.
-* plain-tex-mode: TeX Mode.
-* play-sound: Audible Bell.
-* point-to-register: RegPos.
-* prefer-coding-system: Recognize Coding.
-* prepend-to-buffer: Accumulating Text.
-* previous-complex-command: Repetition.
-* previous-history-element: Minibuffer History.
-* previous-line: Basic.
-* previous-list-mode-item: Completion Commands.
-* previous-matching-history-element: Minibuffer History.
-* print-buffer: Hardcopy.
-* print-diary-entries <1>: Diary Customizing.
-* print-diary-entries: Diary Commands.
-* print-region: Hardcopy.
-* quail-set-keyboard-layout: Select Input Method.
-* query-replace: Query Replace.
-* query-replace-regexp: Query Replace.
-* quietly-read-abbrev-file: Saving Abbrevs.
-* quit-shell-subjob: Shell Mode.
-* quoted-insert: Basic.
-* re-search-backward: Regexp Search.
-* re-search-forward: Regexp Search.
-* read-abbrev-file: Saving Abbrevs.
-* read-key-sequence: Representing Keystrokes.
-* recenter <1>: Scrolling.
-* recenter: Basic.
-* recover-file: Recover.
-* redraw-calendar: General Calendar.
-* relabel-menu-item: Menu Customization.
-* remove-directory: File Names.
-* rename-buffer: Misc Buffer.
-* rename-file: Misc File Ops.
-* repeat-complex-command: Repetition.
-* replace-regexp: Unconditional Replace.
-* replace-string: Unconditional Replace.
-* revert-buffer: Reverting.
-* run-lisp: External Lisp.
-* save-buffer: Saving.
-* save-buffers-kill-emacs: Exiting.
-* save-some-buffers: Saving.
-* scroll-calendar-left: Scroll Calendar.
-* scroll-calendar-left-three-months: Scroll Calendar.
-* scroll-calendar-right: Scroll Calendar.
-* scroll-calendar-right-three-months: Scroll Calendar.
-* scroll-down: Scrolling.
-* scroll-left: Horizontal Scrolling.
-* scroll-other-window <1>: General Calendar.
-* scroll-other-window: Other Window.
-* scroll-right: Horizontal Scrolling.
-* scroll-up: Scrolling.
-* search-backward: Non-Incremental Search.
-* search-forward: Non-Incremental Search.
-* select-input-method: Select Input Method.
-* self-insert: Basic.
-* send-shell-input: Shell Mode.
-* set-buffer-file-coding-system: Specify Coding.
-* set-buffer-process-coding-system: Specify Coding.
-* set-comment-column: Comments.
-* set-default-file-modes: Interlocking.
-* set-face-background: Faces.
-* set-face-background-pixmap: Faces.
-* set-face-font: Faces.
-* set-face-foreground: Faces.
-* set-face-underline-p: Faces.
-* set-fill-column: Fill Commands.
-* set-fill-prefix: Fill Prefix.
-* set-gnu-bindings: Emulation.
-* set-goal-column: Basic.
-* set-gosmacs-bindings: Emulation.
-* set-keyboard-coding-system: Specify Coding.
-* set-language-environment: Language Environments.
-* set-mark-command: Setting Mark.
-* set-selective-display: Selective Display.
-* set-terminal-coding-system: Specify Coding.
-* set-variable: Examining.
-* set-visited-file-name: Saving.
-* setq-default: Locals.
-* shell: Interactive Shell.
-* shell-command: Single Shell.
-* shell-command-on-region: Single Shell.
-* shell-send-eof: Shell Mode.
-* show-all: Outline Visibility.
-* show-all-diary-entries: Diary Commands.
-* show-branches: Outline Visibility.
-* show-children: Outline Visibility.
-* show-entry: Outline Visibility.
-* show-output-from-shell: Shell Mode.
-* show-subtree: Outline Visibility.
-* simple-diary-display: Fancy Diary Display.
-* sort-columns: Sorting.
-* sort-diary-entries: Fancy Diary Display.
-* sort-fields: Sorting.
-* sort-lines: Sorting.
-* sort-numeric-fields: Sorting.
-* sort-pages: Sorting.
-* sort-paragraphs: Sorting.
-* spell-buffer: Spelling.
-* spell-region: Spelling.
-* spell-string: Spelling.
-* spell-word: Spelling.
-* split-line: Indentation Commands.
-* split-window-horizontally: Split Window.
-* split-window-vertically: Split Window.
-* start-kbd-macro: Basic Kbd Macro.
-* stop-shell-subjob: Shell Mode.
-* substitute-key-definition: Interactive Rebinding.
-* sunrise-sunset: Sunrise/Sunset.
-* suspend-emacs: Exiting.
-* switch-to-buffer: Select Buffer.
-* switch-to-buffer-other-frame <1>: Select Buffer.
-* switch-to-buffer-other-frame: XEmacs under X.
-* switch-to-buffer-other-window <1>: Pop Up Window.
-* switch-to-buffer-other-window: Select Buffer.
-* switch-to-other-buffer: Select Buffer.
-* tab-to-tab-stop <1>: Text Mode.
-* tab-to-tab-stop: Tab Stops.
-* tabify: Just Spaces.
-* tags-apropos: List Tags.
-* tags-loop-continue: Tags Search.
-* tags-query-replace: Tags Search.
-* tags-search: Tags Search.
-* term: Terminal emulator.
-* term-line-mode: Term Mode.
-* term-pager-toggle: Paging in Term.
-* tex-buffer: TeX Print.
-* tex-close-latex-block: TeX Editing.
-* tex-insert-braces: TeX Editing.
-* tex-insert-quote: TeX Editing.
-* tex-kill-job: TeX Print.
-* tex-mode: TeX Mode.
-* TeX-mode: TeX Mode.
-* tex-print: TeX Print.
-* tex-recenter-output-buffer: TeX Print.
-* tex-region: TeX Print.
-* tex-show-print-queue: TeX Print.
-* tex-terminate-paragraph: TeX Editing.
-* text-mode: Text Mode.
-* toggle-input-method: Select Input Method.
-* toggle-read-only: Misc Buffer.
-* top-level <1>: Quitting.
-* top-level: Recursive Edit.
-* transpose-chars <1>: Transpose.
-* transpose-chars: Basic.
-* transpose-lines: Transpose.
-* transpose-sexps <1>: Lists.
-* transpose-sexps: Transpose.
-* transpose-words <1>: Words.
-* transpose-words: Transpose.
-* undo: Undo.
-* unexpand-abbrev: Expanding Abbrevs.
-* universal-argument: Arguments.
-* universal-coding-system-argument: Specify Coding.
-* untabify: Just Spaces.
-* up-list: TeX Editing.
-* upcase-region: Case.
-* upcase-word <1>: Case.
-* upcase-word: Fixing Case.
-* validate-tex-buffer: TeX Editing.
-* vc-cancel-version: Editing with VC.
-* vc-create-snapshot: Making Snapshots.
-* vc-diff: Old Versions.
-* vc-directory: VC Status.
-* vc-insert-headers: Version Headers.
-* vc-next-action: Editing with VC.
-* vc-print-log: VC Status.
-* vc-register: Editing with VC.
-* vc-rename-file: Renaming and VC.
-* vc-retrieve-snapshot: Making Snapshots.
-* vc-revert-buffer: Editing with VC.
-* vc-update-change-log: Change Logs and VC.
-* vc-version-other-window: Old Versions.
-* view-buffer: Misc Buffer.
-* view-diary-entries: Diary Commands.
-* view-emacs-news: Help.
-* view-file: Misc File Ops.
-* view-hello-file: Mule Intro.
-* view-lossage: Help.
-* view-register: Registers.
-* visit-tags-table: Select Tags Table.
-* what-cursor-position: Position Info.
-* what-line: Position Info.
-* what-page: Position Info.
-* where-is: Help.
-* widen: Narrowing.
-* widget-backward: Changing an Option.
-* widget-complete: Changing an Option.
-* widget-forward: Changing an Option.
-* window-configuration-to-register <1>: Split Window.
-* window-configuration-to-register: RegConfig.
-* word-search-backward: Word Search.
-* word-search-forward: Word Search.
-* write-abbrev-file: Saving Abbrevs.
-* write-file: Saving.
-* x-copy-primary-selection: X Selection Commands.
-* x-create-frame: X Resources.
-* x-delete-primary-selection: X Selection Commands.
-* x-insert-selection: X Selection Commands.
-* x-kill-primary-selection: X Selection Commands.
-* x-mouse-kill: X Selection Commands.
-* x-own-secondary-selection: X Selection Commands.
-* x-own-selection: X Selection Commands.
-* x-set-point-and-insert-selection: X Selection Commands.
-* Yank: Kill Ring.
-* yank-pop: Earlier Kills.
-* yank-rectangle: Rectangles.
-* yow: Amusements.
-* zap-to-char: Killing.
-* zmacs-activate-region: Active Regions.
-* zmacs-deactivate-region: Active Regions.
+* ! (query-replace): Query Replace.
+* " (TeX mode): TeX Editing.
+* , (query-replace): Query Replace.
+* . (Calendar mode): Specified Dates.
+* . (query-replace): Query Replace.
+* ? (Calendar mode): General Calendar.
+* ^ (query-replace): Query Replace.
+* a (Calendar mode): Holidays.
+* button1: Intro to Keystrokes.
+* button1up: Intro to Keystrokes.
+* button2: Intro to Keystrokes.
+* button2up: Intro to Keystrokes.
+* button3: Intro to Keystrokes.
+* button3up: Intro to Keystrokes.
+* C-<: Setting Mark.
+* C->: Setting Mark.
+* C-@ (Calendar mode): Mark and Region.
+* C-\: Select Input Method.
+* C-] <1>: Quitting.
+* C-]: Recursive Edit.
+* C-_: Undo.
+* C-a: Basic.
+* C-a (Calendar mode): Move to Beginning or End.
+* C-b: Basic.
+* C-b (Calendar mode): Calendar Unit Motion.
+* C-c: Key Sequences.
+* C-c ' (Picture mode): Insert in Picture.
+* C-c . (Picture mode): Insert in Picture.
+* C-c / (Picture mode): Insert in Picture.
+* C-c ; (Fortran mode): Fortran Comments.
+* C-c < (Picture mode): Insert in Picture.
+* C-c > (Picture mode): Insert in Picture.
+* C-c \ (Picture mode): Insert in Picture.
+* C-c ^ (Picture mode): Insert in Picture.
+* C-c ` (Picture mode): Insert in Picture.
+* C-c C-\ (Shell mode): Shell Mode.
+* C-c C-b (Outline mode): Outline Motion.
+* C-c C-b (Picture mode): Insert in Picture.
+* C-c C-b (TeX mode): TeX Print.
+* C-c C-c (Edit Abbrevs): Editing Abbrevs.
+* C-c C-c (Edit Tab Stops): Tab Stops.
+* C-c C-c (Mail mode): Mail Mode.
+* C-c C-c (Occur mode): Other Repeating Search.
+* C-c C-c (Shell mode): Shell Mode.
+* C-c C-d (Picture mode): Basic Picture.
+* C-c C-d (Shell mode): Shell Mode.
+* C-c C-f (LaTeX mode): TeX Editing.
+* C-c C-f (Outline mode): Outline Motion.
+* C-c C-f (Picture mode): Insert in Picture.
+* C-c C-f C-c (Mail mode): Mail Mode.
+* C-c C-f C-s (Mail mode): Mail Mode.
+* C-c C-f C-t (Mail mode): Mail Mode.
+* C-c C-h (Outline mode): Outline Visibility.
+* C-c C-i (Outline mode): Outline Visibility.
+* C-c C-j (Term mode): Term Mode.
+* C-c C-k (Picture mode): Rectangles in Picture.
+* C-c C-k (Term mode): Term Mode.
+* C-c C-k (TeX mode): TeX Print.
+* C-c C-l (Calendar mode): General Calendar.
+* C-c C-l (TeX mode): TeX Print.
+* C-c C-n (Fortran mode): Fortran Motion.
+* C-c C-n (Outline mode): Outline Motion.
+* C-c C-o (Shell mode): Shell Mode.
+* C-c C-p (Fortran mode): Fortran Motion.
+* C-c C-p (Outline mode): Outline Motion.
+* C-c C-p (TeX mode): TeX Print.
+* C-c C-q (Mail mode): Mail Mode.
+* C-c C-q (Term mode): Paging in Term.
+* C-c C-q (TeX mode): TeX Print.
+* C-c C-r (Fortran mode): Fortran Columns.
+* C-c C-r (Shell mode): Shell Mode.
+* C-c C-r (TeX mode): TeX Print.
+* C-c C-s (Mail mode): Mail Mode.
+* C-c C-s (Outline mode): Outline Visibility.
+* C-c C-u (Outline mode): Outline Motion.
+* C-c C-u (Shell mode): Shell Mode.
+* C-c C-w (Fortran mode): Fortran Columns.
+* C-c C-w (Mail mode): Mail Mode.
+* C-c C-w (Picture mode): Rectangles in Picture.
+* C-c C-w (Shell mode): Shell Mode.
+* C-c C-x (Picture mode): Rectangles in Picture.
+* C-c C-y (Mail mode): Mail Mode.
+* C-c C-y (Picture mode): Rectangles in Picture.
+* C-c C-y (Shell mode): Shell Mode.
+* C-c C-z (Shell mode): Shell Mode.
+* C-c TAB (Picture mode): Tabs in Picture.
+* C-c { (TeX mode): TeX Editing.
+* C-c } (TeX mode): TeX Editing.
+* C-d: Killing.
+* C-d (Shell mode): Shell Mode.
+* C-e: Basic.
+* C-e (Calendar mode): Move to Beginning or End.
+* C-END: Basic.
+* C-f: Basic.
+* C-f (Calendar mode): Calendar Unit Motion.
+* C-g <1>: Quitting.
+* C-g: Minibuffer.
+* C-g (isearch-mode): Incremental Search.
+* C-h <1>: Help.
+* C-h: Key Sequences.
+* C-h A: Apropos.
+* C-h b: Misc Help.
+* C-h C: Coding Systems.
+* C-h c: Key Help.
+* C-h C-\: Select Input Method.
+* C-h C-c: Misc Help.
+* C-h C-d: Misc Help.
+* C-h C-f: Misc Help.
+* C-h C-h: Help.
+* C-h C-k: Misc Help.
+* C-h C-w: Misc Help.
+* C-h f: Documentation.
+* C-h F: Misc Help.
+* C-h f: Name Help.
+* C-h h: Mule Intro.
+* C-h I: Select Input Method.
+* C-h i: Misc Help.
+* C-h k: Key Help.
+* C-h L: Language Environments.
+* C-h l: Misc Help.
+* C-h m: Misc Help.
+* C-h n: Misc Help.
+* C-h p: Library Keywords.
+* C-h s: Syntax Change.
+* C-h t <1>: Misc Help.
+* C-h t: Basic.
+* C-h v <1>: Examining.
+* C-h v <2>: Documentation.
+* C-h v: Name Help.
+* C-h w: Name Help.
+* C-HOME: Basic.
+* C-k: Killing.
+* C-l <1>: Scrolling.
+* C-l: Basic.
+* C-l (query-replace): Query Replace.
+* C-LEFT: Basic.
+* C-M-@ <1>: Lists.
+* C-M-@: Marking Objects.
+* C-M-\ <1>: Multi-line Indent.
+* C-M-\: Indentation Commands.
+* C-M-a: Defuns.
+* C-M-a (Fortran mode): Fortran Motion.
+* C-M-b: Lists.
+* C-M-c: Recursive Edit.
+* C-M-d: Lists.
+* C-M-e: Defuns.
+* C-M-e (Fortran mode): Fortran Motion.
+* C-M-f: Lists.
+* C-M-h <1>: Defuns.
+* C-M-h: Marking Objects.
+* C-M-h (Fortran mode): Fortran Motion.
+* C-M-k <1>: Lists.
+* C-M-k: Killing.
+* C-M-n: Lists.
+* C-M-o: Indentation Commands.
+* C-M-p: Lists.
+* C-M-q: Multi-line Indent.
+* C-M-q (Fortran mode): ForIndent Commands.
+* C-M-t <1>: Lists.
+* C-M-t: Transpose.
+* C-M-u: Lists.
+* C-M-v <1>: Other Window.
+* C-M-v: Minibuffer Edit.
+* C-M-w: Appending Kills.
+* C-M-x <1>: External Lisp.
+* C-M-x: Lisp Eval.
+* C-n: Basic.
+* C-n (Calendar mode): Calendar Unit Motion.
+* C-o: Blank Lines.
+* C-p: Basic.
+* C-p (Calendar mode): Calendar Unit Motion.
+* C-q: Basic.
+* C-q (isearch-mode): Incremental Search.
+* C-r: Incremental Search.
+* C-r (isearch-mode): Incremental Search.
+* C-r (query-replace): Query Replace.
+* C-RIGHT: Basic.
+* C-s: Incremental Search.
+* C-s (isearch-mode): Incremental Search.
+* C-SPC: Setting Mark.
+* C-SPC (Calendar mode): Mark and Region.
+* C-t <1>: Transpose.
+* C-t: Basic.
+* C-u: Arguments.
+* C-u - C-x ;: Comments.
+* C-u C-@: Mark Ring.
+* C-u C-SPC: Mark Ring.
+* C-u C-x v v: Editing with VC.
+* C-u TAB: Multi-line Indent.
+* C-v <1>: Scrolling.
+* C-v: Basic.
+* C-v (Calendar mode): Scroll Calendar.
+* C-w: Killing.
+* C-w (isearch-mode): Incremental Search.
+* C-w (query-replace): Query Replace.
+* C-x: Key Sequences.
+* C-x $: Selective Display.
+* C-x (: Basic Kbd Macro.
+* C-x ): Basic Kbd Macro.
+* C-x .: Fill Prefix.
+* C-x 0: Change Window.
+* C-x 1: Change Window.
+* C-x 2: Split Window.
+* C-x 3: Split Window.
+* C-x 4: Pop Up Window.
+* C-x 4 .: Find Tag.
+* C-x 4 b: Select Buffer.
+* C-x 4 d: Dired Enter.
+* C-x 4 f: Visiting.
+* C-x 4 m: Sending Mail.
+* C-x 5 b: Select Buffer.
+* C-x 5 C-f: Visiting.
+* C-x ;: Comments.
+* C-x <: Horizontal Scrolling.
+* C-x < (Calendar mode): Scroll Calendar.
+* C-x =: Position Info.
+* C-x >: Horizontal Scrolling.
+* C-x > (Calendar mode): Scroll Calendar.
+* C-x [: Pages.
+* C-x [ (Calendar mode): Calendar Unit Motion.
+* C-x ]: Pages.
+* C-x ] (Calendar mode): Calendar Unit Motion.
+* C-x ^: Change Window.
+* C-x `: Compilation.
+* C-x a g: Defining Abbrevs.
+* C-x a i g: Defining Abbrevs.
+* C-x a i l: Defining Abbrevs.
+* C-x a l: Defining Abbrevs.
+* C-x b: Select Buffer.
+* C-x C-b: List Buffers.
+* C-x C-c: Exiting.
+* C-x C-d: ListDir.
+* C-x C-e: Lisp Eval.
+* C-x C-l: Case.
+* C-x C-o <1>: Killing.
+* C-x C-o: Blank Lines.
+* C-x C-p <1>: Pages.
+* C-x C-p: Marking Objects.
+* C-x C-q: Misc Buffer.
+* C-x C-q (version control): Editing with VC.
+* C-x C-s: Saving.
+* C-x C-t: Transpose.
+* C-x C-u: Case.
+* C-x C-v: Visiting.
+* C-x C-w: Saving.
+* C-x C-x: Setting Mark.
+* C-x C-x (Calendar mode): Mark and Region.
+* C-x d: Dired Enter.
+* C-x DEL <1>: Sentences.
+* C-x DEL <2>: Kill Errors.
+* C-x DEL: Killing.
+* C-x e: Basic Kbd Macro.
+* C-x ESC ESC: Repetition.
+* C-x f: Fill Commands.
+* C-x h: Marking Objects.
+* C-x k: Kill Buffer.
+* C-x l: Pages.
+* C-x m: Sending Mail.
+* C-x n n: Narrowing.
+* C-x n w: Narrowing.
+* C-x o: Other Window.
+* C-x q: Kbd Macro Query.
+* C-x r +: RegNumbers.
+* C-x r b: Bookmarks.
+* C-x r g: RegText.
+* C-x r i: RegText.
+* C-x r j: RegPos.
+* C-x r l: Bookmarks.
+* C-x r m: Bookmarks.
+* C-x r n: RegNumbers.
+* C-x r r: RegRect.
+* C-x r s: RegText.
+* C-x r SPC: RegPos.
+* C-x r w: RegConfig.
+* C-x RET: Mule Intro.
+* C-x RET c: Specify Coding.
+* C-x RET C-\: Select Input Method.
+* C-x RET f: Specify Coding.
+* C-x RET k: Specify Coding.
+* C-x RET p: Specify Coding.
+* C-x RET t: Specify Coding.
+* C-x s: Saving.
+* C-x TAB: Indentation Commands.
+* C-x u: Undo.
+* C-x v =: Old Versions.
+* C-x v a: Change Logs and VC.
+* C-x v c: Editing with VC.
+* C-x v d: VC Status.
+* C-x v h: Version Headers.
+* C-x v i: Editing with VC.
+* C-x v l: VC Status.
+* C-x v r: Making Snapshots.
+* C-x v s: Making Snapshots.
+* C-x v u: Editing with VC.
+* C-x v ~: Old Versions.
+* C-x }: Change Window.
+* C-y: Kill Ring.
+* C-y (isearch-mode): Incremental Search.
+* C-z: Exiting.
+* control key: Intro to Keystrokes.
+* d (Calendar mode): Diary Commands.
+* DEL <1>: Program Modes.
+* DEL <2>: Major Modes.
+* DEL <3>: Kill Errors.
+* DEL <4>: Killing.
+* DEL: Basic.
+* DEL (isearch-mode): Incremental Search.
+* DEL (query-replace): Query Replace.
+* DOWN: Basic.
+* END: Basic.
+* ESC <1>: Meta Key.
+* ESC: Key Sequences.
+* ESC (query-replace): Query Replace.
+* F1: Help.
+* g CHAR (Calendar mode): From Other Calendar.
+* g d (Calendar mode): Specified Dates.
+* g m l (Calendar mode): Mayan Calendar.
+* h (Calendar mode): Holidays.
+* Help: Help.
+* HOME: Basic.
+* hyper key <1>: Super and Hyper Keys.
+* hyper key <2>: Representing Keystrokes.
+* hyper key: Intro to Keystrokes.
+* i a (Calendar mode): Special Diary Entries.
+* i b (Calendar mode): Special Diary Entries.
+* i c (Calendar mode): Special Diary Entries.
+* i d (Calendar mode): Adding to Diary.
+* i m (Calendar mode): Adding to Diary.
+* i w (Calendar mode): Adding to Diary.
+* i y (Calendar mode): Adding to Diary.
+* LEFT: Basic.
+* LFD <1>: Basic Indent.
+* LFD <2>: Major Modes.
+* LFD: String Key Sequences.
+* LFD (TeX mode): TeX Editing.
+* m (Calendar mode): Diary Commands.
+* M (Calendar mode): Lunar Phases.
+* M-!: Single Shell.
+* M-$: Spelling.
+* M-%: Query Replace.
+* M-': Expanding Abbrevs.
+* M-(: Balanced Editing.
+* M-): Balanced Editing.
+* M-,: Tags Search.
+* M--: Arguments.
+* M-- M-c: Fixing Case.
+* M-- M-l: Fixing Case.
+* M-- M-u: Fixing Case.
+* M-.: Find Tag.
+* M-/: Dynamic Abbrevs.
+* M-1: Arguments.
+* M-;: Comments.
+* M-<: Basic.
+* M-< (Calendar mode): Move to Beginning or End.
+* M-=: Position Info.
+* M-= (Calendar mode): Mark and Region.
+* M->: Basic.
+* M-> (Calendar mode): Move to Beginning or End.
+* M-?: Nroff Mode.
+* M-@ <1>: Words.
+* M-@: Marking Objects.
+* M-[: Paragraphs.
+* M-\ <1>: Indentation Commands.
+* M-\: Killing.
+* M-]: Paragraphs.
+* M-^ <1>: Indentation Commands.
+* M-^: Killing.
+* M-a: Sentences.
+* M-a (Calendar mode): Move to Beginning or End.
+* M-b: Words.
+* M-c: Case.
+* M-C-s: Regexp Search.
+* M-d <1>: Words.
+* M-d: Killing.
+* M-DEL <1>: Words.
+* M-DEL <2>: Kill Errors.
+* M-DEL: Killing.
+* M-e: Sentences.
+* M-e (Calendar mode): Move to Beginning or End.
+* M-ESC: Lisp Eval.
+* M-f: Words.
+* M-g: Fill Commands.
+* M-h <1>: Paragraphs.
+* M-h: Marking Objects.
+* M-i: Tab Stops.
+* M-k <1>: Sentences.
+* M-k: Killing.
+* M-l: Case.
+* M-LFD: Comments.
+* M-LFD (Fortran mode): ForIndent Commands.
+* M-m: Indentation Commands.
+* M-n <1>: Nroff Mode.
+* M-n: Repetition.
+* M-n (isearch-mode): Incremental Search.
+* M-n (minibuffer history): Minibuffer History.
+* M-n (Shell mode): Shell Mode.
+* M-p <1>: Nroff Mode.
+* M-p: Repetition.
+* M-p (isearch-mode): Incremental Search.
+* M-p (minibuffer history): Minibuffer History.
+* M-p (Shell mode): Shell Mode.
+* M-q: Fill Commands.
+* M-r: Basic.
+* M-r (minibuffer history): Minibuffer History.
+* M-s: Fill Commands.
+* M-s (minibuffer history): Minibuffer History.
+* M-SPC: Killing.
+* M-t <1>: Words.
+* M-t: Transpose.
+* M-TAB <1>: Tabs in Picture.
+* M-TAB: Lisp Completion.
+* M-TAB (customization buffer): Changing an Option.
+* M-TAB (isearch-mode): Incremental Search.
+* M-u: Case.
+* M-v <1>: Scrolling.
+* M-v: Basic.
+* M-v (Calendar mode): Scroll Calendar.
+* M-w: Kill Ring.
+* M-x: M-x.
+* M-y: Earlier Kills.
+* M-z: Killing.
+* M-{ (Calendar mode): Calendar Unit Motion.
+* M-|: Single Shell.
+* M-} (Calendar mode): Calendar Unit Motion.
+* M-~: Saving.
+* META: Meta Key.
+* meta key: Intro to Keystrokes.
+* next: Scrolling.
+* o (Calendar mode): Specified Dates.
+* p (Calendar mode): To Other Calendar.
+* p d (Calendar mode): General Calendar.
+* pgdn: Scrolling.
+* PGDN: Basic.
+* pgup: Scrolling.
+* PGUP: Basic.
+* prior: Scrolling.
+* q (Calendar mode): General Calendar.
+* RET: Basic.
+* RET (isearch-mode): Incremental Search.
+* RET (Shell mode): Shell Mode.
+* RIGHT: Basic.
+* s (Calendar mode): Diary Commands.
+* S (Calendar mode): Sunrise/Sunset.
+* S-TAB (customization buffer): Changing an Option.
+* shift key: Intro to Keystrokes.
+* SPC: Completion Commands.
+* SPC (Calendar mode): General Calendar.
+* SPC (query-replace): Query Replace.
+* super key <1>: Super and Hyper Keys.
+* super key <2>: Representing Keystrokes.
+* super key: Intro to Keystrokes.
+* t (Calendar mode): LaTeX Calendar.
+* TAB <1>: Basic Indent.
+* TAB <2>: Text Mode.
+* TAB <3>: Indentation.
+* TAB <4>: Major Modes.
+* TAB <5>: Completion Example.
+* TAB: String Key Sequences.
+* TAB (customization buffer): Changing an Option.
+* TAB (Shell mode): Shell Mode.
+* u (Calendar mode) <1>: Diary Commands.
+* u (Calendar mode): Holidays.
+* UP: Basic.
+* x (Calendar mode): Holidays.
translation approved by the author instead of in the original English.
\1f
-File: xemacs.info, Node: Variable Index, Next: Concept Index, Prev: Command Index, Up: Top
+File: xemacs.info, Node: Command Index, Next: Variable Index, Prev: Key Index, Up: Top
-Variable Index
-**************
+Command and Function Index
+**************************
* Menu:
-* abbrev-all-caps: Expanding Abbrevs.
-* abbrev-file-name: Saving Abbrevs.
+* abbrev-mode <1>: Minor Modes.
* abbrev-mode: Abbrevs.
-* after-load-alist: Loading.
-* after-save-hook: Saving.
-* all-christian-calendar-holidays: Holiday Customizing.
-* all-hebrew-calendar-holidays: Holiday Customizing.
-* all-islamic-calendar-holidays: Holiday Customizing.
-* appt-audible: Appt Customizing.
-* appt-display-duration: Appt Customizing.
-* appt-display-mode-line: Appt Customizing.
-* appt-message-warning-time: Appt Customizing.
-* appt-msg-window: Appt Customizing.
-* appt-visible: Appt Customizing.
-* auto-fill-inhibit-regexp: Fill Commands.
-* auto-lower-frame: XEmacs under X.
-* auto-mode-alist: Choosing Modes.
-* auto-raise-frame: XEmacs under X.
-* auto-save-default: Auto Save Control.
-* auto-save-interval: Auto Save Control.
-* auto-save-timeout: Auto Save Control.
-* auto-save-visited-file-name: Auto Save Files.
-* backup-by-copying: Backup Copying.
-* backup-by-copying-when-linked: Backup Copying.
-* backup-by-copying-when-mismatch: Backup Copying.
-* bell-volume: Audible Bell.
-* blink-matching-paren: Matching.
-* blink-matching-paren-distance: Matching.
-* bookmark-save-flag: Bookmarks.
-* bookmark-search-size: Bookmarks.
-* buffer-file-coding-system: Recognize Coding.
-* buffer-file-name: Visiting.
-* buffer-file-truename: Visiting.
-* buffer-read-only: Misc Buffer.
-* buffer-tag-table: Find Tag.
-* c-argdecl-indent: C Indent.
-* c-auto-newline: C Indent.
-* c-brace-imaginary-offset: C Indent.
-* c-brace-offset: C Indent.
-* c-continued-statement-offset: C Indent.
-* c-indent-level: C Indent.
-* c-label-offset: C Indent.
-* c-mode-hook: Program Modes.
-* c-mode-map: Keymaps.
-* c-tab-always-indent: C Indent.
-* calendar-date-display-form: Date Display Format.
-* calendar-daylight-savings-ends: Daylight Savings.
-* calendar-daylight-savings-ends-time: Daylight Savings.
-* calendar-daylight-savings-starts: Daylight Savings.
-* calendar-daylight-time-offset: Daylight Savings.
-* calendar-daylight-time-zone-name: Sunrise/Sunset.
-* calendar-holiday-marker: Calendar Customizing.
-* calendar-holidays: Holiday Customizing.
-* calendar-latitude: Sunrise/Sunset.
-* calendar-load-hook: Calendar Customizing.
-* calendar-location-name: Sunrise/Sunset.
-* calendar-longitude: Sunrise/Sunset.
-* calendar-standard-time-zone-name: Sunrise/Sunset.
-* calendar-time-display-form: Time Display Format.
-* calendar-time-zone: Sunrise/Sunset.
-* calendar-today-marker: Calendar Customizing.
-* calendar-week-start-day: Move to Beginning or End.
-* case-fold-search <1>: Replacement and Case.
-* case-fold-search: Search Case.
-* case-replace: Replacement and Case.
-* christian-holidays: Holiday Customizing.
-* coding: Recognize Coding.
-* command-history: Repetition.
-* command-line-args: Command Switches.
-* comment-column: Comments.
-* comment-end: Comments.
-* comment-indent-hook: Comments.
-* comment-line-start: Fortran Comments.
-* comment-line-start-skip: Fortran Comments.
-* comment-multi-line: Comments.
-* comment-start: Comments.
-* comment-start-skip: Comments.
-* compare-ignore-case: Comparing Files.
-* compile-command: Compilation.
-* completion-auto-help: Completion Options.
-* completion-ignored-extensions: Completion Options.
-* create-frame-hook: XEmacs under X.
-* ctl-arrow: Display Vars.
-* ctl-x-map: Keymaps.
-* current-input-method: Select Input Method.
-* data-directory: Startup Paths.
-* data-directory-list: Startup Paths.
-* debug-on-error: Lisp Debug.
-* debug-on-quit: Lisp Debug.
-* default-buffer-file-coding-system: Specify Coding.
-* default-directory: File Names.
-* default-directory-alist: File Names.
-* default-frame-alist: XEmacs under X.
-* default-input-method: Select Input Method.
-* default-major-mode: Choosing Modes.
-* delete-auto-save-files: Auto Save Files.
-* delete-old-versions: Backup Deletion.
-* describe-function-show-arglist: Help.
-* diary-date-forms: Diary Customizing.
-* diary-display-hook: Fancy Diary Display.
-* diary-entry-marker: Calendar Customizing.
-* diary-file: Format of Diary File.
-* diary-list-include-blanks: Fancy Diary Display.
-* diary-mail-days: Diary Commands.
-* diff-switches: Comparing Files.
-* dired-kept-versions: Dired Deletion.
-* dired-listing-switches: Dired Enter.
-* display-buffer-function: Pop Up Window.
-* doc-directory: Startup Paths.
-* echo-keystrokes: Display Vars.
-* emacs-lisp-mode-hook: Program Modes.
-* emacs-roots: Startup Paths.
-* EMACSDATA: Startup Paths.
-* EMACSLOADPATH: Startup Paths.
-* EMACSLOCKDIR: Startup Paths.
-* EMACSPATH: Startup Paths.
-* enable-local-variables: File Variables.
-* enable-recursive-minibuffers: Minibuffer Edit.
-* esc-map: Keymaps.
-* european-calendar-style: Date Formats.
-* exec-directory: Startup Paths.
-* exec-path: Startup Paths.
-* explicit-shell-file-name: Interactive Shell.
-* file-coding-system-alist: Recognize Coding.
-* file-name-coding-system: Specify Coding.
-* fill-column: Fill Commands.
-* fill-prefix: Fill Prefix.
-* find-file-compare-truenames: Visiting.
-* find-file-hooks: Visiting.
-* find-file-not-found-hooks: Visiting.
-* find-file-run-dired: Visiting.
-* find-file-use-truenames: Visiting.
-* fortran-check-all-num-for-matching-do: ForIndent Vars.
-* fortran-comment-indent-char: Fortran Comments.
-* fortran-comment-indent-style: Fortran Comments.
-* fortran-comment-line-column: Fortran Comments.
-* fortran-comment-region: Fortran Comments.
-* fortran-continuation-char: ForIndent Conv.
-* fortran-continuation-indent: ForIndent Vars.
-* fortran-do-indent: ForIndent Vars.
-* fortran-electric-line-number: ForIndent Num.
-* fortran-if-indent: ForIndent Vars.
-* fortran-line-number-indent: ForIndent Num.
-* fortran-minimum-statement-indent: ForIndent Vars.
-* frame-icon-title-format <1>: Command Switches.
-* frame-icon-title-format: XEmacs under X.
-* frame-title-format <1>: Command Switches.
-* frame-title-format: XEmacs under X.
-* general-holidays: Holiday Customizing.
-* global-map: Keymaps.
-* hebrew-holidays: Holiday Customizing.
-* help-map: Keymaps.
-* holidays-in-diary-buffer: Diary Customizing.
-* indent-tabs-mode: Just Spaces.
-* Info-directory-list: Startup Paths.
-* INFOPATH: Startup Paths.
-* initial-calendar-window-hook: Calendar Customizing.
-* initial-major-mode: Entering Emacs.
-* input-method-highlight-flag: Input Methods.
-* input-method-verbose-flag: Input Methods.
-* input-ring-size: Interactive Shell.
-* insert-default-directory <1>: File Names.
-* insert-default-directory: Minibuffer File.
-* isearch-mode-map: Keymaps.
-* islamic-holidays: Holiday Customizing.
-* kept-new-versions: Backup Deletion.
-* kept-old-versions: Backup Deletion.
-* keyboard-translate-table: Intro to Keystrokes.
-* kill-ring-max: Earlier Kills.
-* LaTeX-mode-hook: TeX Print.
-* lisp-body-indention: Lisp Indent.
-* lisp-directory: Startup Paths.
-* lisp-indent-offset: Lisp Indent.
-* lisp-interaction-mode-hook: Program Modes.
-* lisp-mode-hook: Program Modes.
-* lisp-mode-map: Keymaps.
-* list-diary-entries-hook: Included Diary Files.
-* list-directory-brief-switches: ListDir.
-* list-directory-verbose-switches: ListDir.
-* load-path <1>: Loading.
-* load-path: Startup Paths.
-* local-holidays: Holiday Customizing.
-* lock-directory: Startup Paths.
-* lpr-switches: Hardcopy.
-* mail-abbrev-mailrc-file: Mail Headers.
-* mail-abbrev-mode-regexp: Mail Headers.
-* mail-alias-seperator-string: Mail Headers.
-* mail-archive-file-name: Mail Headers.
-* mail-header-separator: Mail Format.
-* mail-mode-hook: Mail Mode.
-* make-backup-files: Backup.
-* make-tags-files-invisible: Find Tag.
-* mark-diary-entries-hook: Included Diary Files.
-* mark-diary-entries-in-calendar: Calendar Customizing.
-* mark-holidays-in-calendar: Calendar Customizing.
-* mark-ring: Mark Ring.
-* mark-ring-max: Mark Ring.
-* meta-flag: Meta Key.
-* minibuffer-confirm-incomplete <1>: Completion Options.
-* minibuffer-confirm-incomplete: Minibuffer Edit.
-* minibuffer-local-completion-map: Keymaps.
-* minibuffer-local-map: Keymaps.
-* minibuffer-local-must-match-map: Keymaps.
-* minibuffer-local-ns-map: Keymaps.
-* mode-line-inverse-video: Mode Line.
-* modeline-pointer-glyph: Mouse Selection.
-* muddle-mode-hook: Program Modes.
-* next-screen-context-lines: Scrolling.
-* no-redraw-on-reenter: Display Vars.
-* nongregorian-diary-listing-hook: Hebrew/Islamic Entries.
-* nongregorian-diary-marking-hook: Hebrew/Islamic Entries.
-* nontext-pointer-glyph: Mouse Selection.
-* nroff-mode-hook: Nroff Mode.
-* number-of-diary-entries: Diary Customizing.
-* other-holidays: Holiday Customizing.
-* outline-mode-hook: Outline Mode.
-* outline-regexp: Outline Format.
-* page-delimiter: Pages.
-* paragraph-separate: Paragraphs.
-* paragraph-start: Paragraphs.
-* parse-sexp-ignore-comments: Syntax Entry.
-* PATH: Startup Paths.
-* picture-mode-hook: Picture.
-* picture-tab-chars: Tabs in Picture.
-* plain-TeX-mode-hook: TeX Print.
-* print-diary-entries-hook: Diary Customizing.
-* repeat-complex-command-map: Keymaps.
-* require-final-newline: Saving.
-* save-abbrevs: Saving Abbrevs.
-* scheme-mode-hook: Program Modes.
-* scroll-conservatively: Scrolling.
-* scroll-step: Scrolling.
-* search-slow-speed: Incremental Search.
-* search-slow-window-lines: Incremental Search.
-* selective-display-ellipses <1>: Outline Visibility.
-* selective-display-ellipses: Display Vars.
-* sentence-end: Sentences.
-* shell-cd-regexp: Interactive Shell.
-* shell-file-name: Single Shell.
-* shell-popd-regexp: Interactive Shell.
-* shell-prompt-pattern: Shell Mode.
-* shell-pushd-regexp: Interactive Shell.
-* sound-alist: Audible Bell.
-* superlock-file: Startup Paths.
-* tab-stop-list: Tab Stops.
-* tab-width: Display Vars.
-* tag-mark-stack-max: Find Tag.
-* tag-table-alist <1>: Find Tag.
-* tag-table-alist: Select Tags Table.
-* tags-always-build-completion-table: Select Tags Table.
-* tags-build-completion-table: Find Tag.
-* tags-file-name <1>: Find Tag.
-* tags-file-name: Select Tags Table.
-* term-file-prefix: Terminal Init.
-* term-setup-hook: Terminal Init.
-* TeX-mode-hook: TeX Print.
-* text-mode-hook: Text Mode.
-* text-pointer-glyph: Mouse Selection.
-* today-invisible-calendar-hook: Calendar Customizing.
-* today-visible-calendar-hook: Calendar Customizing.
-* track-eol: Basic.
-* truncate-lines: Continuation Lines.
-* truncate-partial-width-windows: Split Window.
-* vc-command-messages: Variables for Check-in/out.
-* vc-comment-alist: Version Headers.
-* vc-default-back-end: Editing with VC.
-* vc-header-alist: Version Headers.
-* vc-initial-comment: Editing with VC.
-* vc-keep-workfiles: Editing with VC.
-* vc-log-mode-hook: Log Entries.
-* vc-make-backup-files: Editing with VC.
-* vc-mistrust-permissions: Variables for Check-in/out.
-* vc-path: Variables for Check-in/out.
-* vc-static-header-alist: Version Headers.
-* vc-suppress-confirm: Variables for Check-in/out.
-* version-control: Backup Names.
-* view-calendar-holidays-initially: Calendar Customizing.
-* view-diary-entries-initially: Calendar Customizing.
-* window-min-height: Change Window.
-* window-min-width: Change Window.
-* write-file-hooks: Saving.
-* x-frame-defaults: XEmacs under X.
-* zmacs-region-stays: Active Regions.
-* zmacs-regions: Active Regions.
-
-\1f
-File: xemacs.info, Node: Concept Index, Next: Frame, Prev: Variable Index, Up: Top
-
-Concept Index
-*************
-
-* Menu:
-
-* .mailrc file: Mail Headers.
-* // in file name: Minibuffer File.
-* Abbrev mode: Minor Modes.
-* abbrevs: Abbrevs.
-* aborting: Quitting.
-* accumulating text: Accumulating Text.
-* active fields (customization buffer): Customization Groups.
-* active regions: Active Regions.
-* adding menu items: Menu Customization.
-* adding menus: Menu Customization.
-* againformation: Dissociated Press.
-* Apps menu <1>: Apps Menu.
-* Apps menu: Pull-down Menus.
-* apropos: Help.
-* architecture-specific directories: Startup Paths.
-* arguments (from shell): Command Switches.
-* ASCII: Intro to Keystrokes.
-* Asm mode: Asm Mode.
-* astronomical day numbers: Calendar Systems.
-* audible bell, changing: Audible Bell.
-* Auto Delete Selection menu item: Options Menu.
-* Auto Fill mode <1>: Minor Modes.
-* Auto Fill mode <2>: Comments.
-* Auto Fill mode: Auto Fill.
-* Auto-Save mode: Auto Save.
-* autoload: Loading.
-* backup file: Backup.
-* batch mode: Command Switches.
-* bell, changing: Audible Bell.
-* binary packages: Package Terminology.
-* binding: Commands.
-* blank lines <1>: Comments.
-* blank lines: Blank Lines.
-* body lines (Outline mode): Outline Format.
-* bold font: Face Customization.
-* bookmarks: Bookmarks.
-* boredom: Amusements.
-* buffer: Frame.
-* buffer menu: Several Buffers.
-* buffers: Buffers.
-* Buffers menu <1>: Buffers Menu.
-* Buffers menu: Pull-down Menus.
-* Buffers Menu Length... menu item: Options Menu.
-* Buffers Sub-Menus menu item: Options Menu.
-* buggestion: Dissociated Press.
-* bugs: Bugs.
-* byte code: Compiling Libraries.
-* C: Programs.
-* C mode: Program Modes.
+* abbrev-prefix-mark: Expanding Abbrevs.
+* abort-recursive-edit <1>: Quitting.
+* abort-recursive-edit: Recursive Edit.
+* add-change-log-entry: Change Log.
+* add-global-abbrev: Defining Abbrevs.
+* add-menu: Menu Customization.
+* add-menu-item: Menu Customization.
+* add-mode-abbrev: Defining Abbrevs.
+* add-name-to-file: Misc File Ops.
+* american-calendar: Date Formats.
+* append-next-kill: Appending Kills.
+* append-to-buffer: Accumulating Text.
+* append-to-file <1>: Misc File Ops.
+* append-to-file: Accumulating Text.
+* apropos: Apropos.
+* apropos-documentation: Apropos.
+* apropos-value: Apropos.
+* ask-user-about-lock: Interlocking.
+* auto-fill-mode <1>: Minor Modes.
+* auto-fill-mode: Auto Fill.
+* auto-save-mode: Auto Save Control.
+* back-to-indentation: Indentation Commands.
+* backward-char: Basic.
+* backward-delete-char-untabify: Program Modes.
+* backward-kill-sentence <1>: Sentences.
+* backward-kill-sentence <2>: Kill Errors.
+* backward-kill-sentence: Killing.
+* backward-kill-word <1>: Words.
+* backward-kill-word <2>: Kill Errors.
+* backward-kill-word: Killing.
+* backward-list: Lists.
+* backward-page: Pages.
+* backward-paragraph: Paragraphs.
+* backward-sentence: Sentences.
+* backward-sexp: Lists.
+* backward-text-line: Nroff Mode.
+* backward-up-list: Lists.
+* backward-word: Words.
+* batch-byte-compile: Compiling Libraries.
+* beginning-of-buffer: Basic.
+* beginning-of-defun: Defuns.
+* beginning-of-fortran-subprogram: Fortran Motion.
+* beginning-of-line: Basic.
+* bookmark-delete: Bookmarks.
+* bookmark-insert: Bookmarks.
+* bookmark-insert-location: Bookmarks.
+* bookmark-jump: Bookmarks.
+* bookmark-load: Bookmarks.
+* bookmark-save: Bookmarks.
+* bookmark-set: Bookmarks.
+* bookmark-write: Bookmarks.
+* buffer-menu: Several Buffers.
+* byte-compile-and-load-file: Compiling Libraries.
+* byte-compile-buffer: Compiling Libraries.
+* byte-compile-file: Compiling Libraries.
+* byte-recompile-directory: Compiling Libraries.
+* c-indent-line: Basic Indent.
* calendar: Calendar/Diary.
-* calendar and LaTeX: LaTeX Calendar.
-* calendar, first day of week: Move to Beginning or End.
-* candle lighting times: Sexp Diary Entries.
-* case conversion <1>: Case.
-* case conversion: Fixing Case.
-* Case Sensitive Search menu item: Options Menu.
-* centering: Fill Commands.
-* change log: Change Log.
-* changing buffers: Select Buffer.
-* changing menu items: Menu Customization.
-* character set: Intro to Keystrokes.
-* checking in files: Concepts of VC.
-* checking out files: Concepts of VC.
-* Chinese: Mule.
-* Chinese calendar: Calendar Systems.
-* Clear menu item: Edit Menu.
-* clipboard selections: X Clipboard Selection.
-* coding systems: Coding Systems.
-* command <1>: Key Bindings.
-* command: Commands.
-* command history: Repetition.
-* command line arguments: Command Switches.
-* command name: Key Bindings.
-* comments: Comments.
-* comparing files: Comparing Files.
-* compilation errors: Compilation.
-* compiling files: Compilation.
-* completion: Completion.
-* completion (symbol names): Lisp Completion.
-* continuation line: Continuation Lines.
-* Control-Meta: Lists.
-* Coptic calendar: Calendar Systems.
-* Copy menu item: Edit Menu.
-* copying files: Misc File Ops.
-* copying text <1>: Accumulating Text.
-* copying text: Yanking.
-* core distribution: Using Packages.
-* crashes: Auto Save.
-* creating directories: File Names.
-* creating files: Visiting.
-* current buffer: Buffers.
-* current stack frame: Lisp Debug.
-* cursor <1>: Basic.
-* cursor: Point.
-* customization <1>: Customization.
-* customization <2>: Lisp Indent.
-* customization: Commands.
-* customization buffer: Easy Customization.
-* customization groups: Customization Groups.
-* customizing faces: Face Customization.
-* cut buffers: X Selection Commands.
-* Cut menu item: Edit Menu.
-* cutting: Killing.
-* day of year: General Calendar.
-* daylight savings time: Daylight Savings.
-* debugger: Lisp Debug.
-* default argument: Minibuffer.
-* defuns: Defuns.
-* Delete Frame menu item: File Menu.
-* deleting menu items: Menu Customization.
-* deletion <1>: Killing.
-* deletion: Basic.
-* deletion (of files) <1>: Misc File Ops.
-* deletion (of files): Dired.
-* diary: Diary.
-* diary buffer: Fancy Diary Display.
-* diary file: Format of Diary File.
-* ding: Audible Bell.
-* directories: Startup Paths.
-* directory hierarchies: Startup Paths.
-* directory listing: ListDir.
-* Dired: Dired.
-* disabled command: Disabling.
-* disabling menu items: Menu Customization.
-* Distribution: License.
+* calendar-backward-day: Calendar Unit Motion.
+* calendar-backward-month: Calendar Unit Motion.
+* calendar-backward-week: Calendar Unit Motion.
+* calendar-beginning-of-month: Move to Beginning or End.
+* calendar-beginning-of-week: Move to Beginning or End.
+* calendar-beginning-of-year: Move to Beginning or End.
+* calendar-count-days-region: Mark and Region.
+* calendar-cursor-holidays: Holidays.
+* calendar-end-of-month: Move to Beginning or End.
+* calendar-end-of-week: Move to Beginning or End.
+* calendar-end-of-year: Move to Beginning or End.
+* calendar-exchange-point-and-mark: Mark and Region.
+* calendar-forward-day: Calendar Unit Motion.
+* calendar-forward-month: Calendar Unit Motion.
+* calendar-forward-week: Calendar Unit Motion.
+* calendar-forward-year: Calendar Unit Motion.
+* calendar-goto-astro-day-number: From Other Calendar.
+* calendar-goto-chinese-date: From Other Calendar.
+* calendar-goto-coptic-date: From Other Calendar.
+* calendar-goto-date: Specified Dates.
+* calendar-goto-ethiopic-date: From Other Calendar.
+* calendar-goto-french-date: From Other Calendar.
+* calendar-goto-hebrew-date: From Other Calendar.
+* calendar-goto-islamic-date: From Other Calendar.
+* calendar-goto-iso-date: From Other Calendar.
+* calendar-goto-julian-date: From Other Calendar.
+* calendar-goto-mayan-long-count-date: Mayan Calendar.
+* calendar-goto-persian-date: From Other Calendar.
+* calendar-goto-today: Specified Dates.
+* calendar-mark-today: Calendar Customizing.
+* calendar-next-calendar-round-date: Mayan Calendar.
+* calendar-next-haab-date: Mayan Calendar.
+* calendar-next-tzolkin-date: Mayan Calendar.
+* calendar-other-month: Specified Dates.
+* calendar-phases-of-moon: Lunar Phases.
+* calendar-previous-haab-date: Mayan Calendar.
+* calendar-previous-tzolkin-date: Mayan Calendar.
+* calendar-print-astro-day-number: To Other Calendar.
+* calendar-print-chinese-date: To Other Calendar.
+* calendar-print-coptic-date: To Other Calendar.
+* calendar-print-day-of-year: General Calendar.
+* calendar-print-ethiopic-date: To Other Calendar.
+* calendar-print-french-date: To Other Calendar.
+* calendar-print-hebrew-date: To Other Calendar.
+* calendar-print-islamic-date: To Other Calendar.
+* calendar-print-iso-date: To Other Calendar.
+* calendar-print-julian-date: To Other Calendar.
+* calendar-print-mayan-date: To Other Calendar.
+* calendar-print-persian-date: To Other Calendar.
+* calendar-set-mark: Mark and Region.
+* calendar-star-date: Calendar Customizing.
+* calendar-sunrise-sunset: Sunrise/Sunset.
+* calendar-unmark <1>: Diary Commands.
+* calendar-unmark: Holidays.
+* call-last-kbd-macro: Basic Kbd Macro.
+* cancel-debug-on-entry: Lisp Debug.
+* capitalize-word <1>: Case.
+* capitalize-word: Fixing Case.
+* center-line: Fill Commands.
+* choose-completion: Completion Commands.
+* clear-rectangle: Rectangles.
+* comint-delchar-or-maybe-eof: Shell Mode.
+* comint-dynamic-complete: Shell Mode.
+* comint-next-input: Shell Mode.
+* comint-previous-input: Shell Mode.
+* command-apropos: Apropos.
+* compare-windows <1>: Other Window.
+* compare-windows: Comparing Files.
+* compile: Compilation.
+* compile-defun: Defuns.
+* convert-mocklisp-buffer: Mocklisp.
+* conx: CONX.
+* conx-buffer: CONX.
+* conx-init: CONX.
+* conx-load: CONX.
+* conx-region: CONX.
+* conx-save: CONX.
+* copy-file: Misc File Ops.
+* copy-last-shell-input: Shell Mode.
+* copy-rectangle-to-register: RegRect.
+* copy-region-as-kill: Kill Ring.
+* copy-to-buffer: Accumulating Text.
+* copy-to-register: RegText.
+* count-lines-page: Pages.
+* count-lines-region: Position Info.
+* count-matches: Other Repeating Search.
+* count-text-lines: Nroff Mode.
+* customize: Easy Customization.
+* customize-apropos: Specific Customization.
+* customize-browse: Customization Groups.
+* customize-customized: Specific Customization.
+* customize-face: Specific Customization.
+* customize-group: Specific Customization.
+* customize-option: Specific Customization.
+* customize-saved: Specific Customization.
+* dabbrev-expand: Dynamic Abbrevs.
+* debug: Lisp Debug.
+* debug-on-entry: Lisp Debug.
+* default-value: Locals.
+* define-abbrevs: Saving Abbrevs.
+* define-key <1>: Programmatic Rebinding.
+* define-key: Interactive Rebinding.
+* delete-backward-char <1>: Kill Errors.
+* delete-backward-char <2>: Killing.
+* delete-backward-char: Basic.
+* delete-blank-lines <1>: Killing.
+* delete-blank-lines: Blank Lines.
+* delete-char <1>: Basic Picture.
+* delete-char: Killing.
+* delete-file: Misc File Ops.
+* delete-horizontal-space <1>: Indentation Commands.
+* delete-horizontal-space: Killing.
+* delete-indentation <1>: Indentation Commands.
+* delete-indentation: Killing.
+* delete-matching-lines: Other Repeating Search.
+* delete-menu-item: Menu Customization.
+* delete-non-matching-lines: Other Repeating Search.
+* delete-other-windows: Change Window.
+* delete-rectangle: Rectangles.
+* delete-window: Change Window.
+* describe-bindings: Misc Help.
+* describe-calendar-mode: General Calendar.
+* describe-coding-system: Coding Systems.
+* describe-copying: Misc Help.
+* describe-distribution: Misc Help.
+* describe-function <1>: Documentation.
+* describe-function: Name Help.
+* describe-input-method: Select Input Method.
+* describe-key: Key Help.
+* describe-key-briefly: Key Help.
+* describe-language-environment: Language Environments.
+* describe-mode: Misc Help.
+* describe-no-warranty: Misc Help.
+* describe-syntax: Syntax Change.
+* describe-variable <1>: Examining.
+* describe-variable <2>: Documentation.
+* describe-variable: Name Help.
+* diary: Diary Commands.
+* diary-anniversary <1>: Sexp Diary Entries.
+* diary-anniversary: Special Diary Entries.
+* diary-astro-day-number: Sexp Diary Entries.
+* diary-block: Special Diary Entries.
+* diary-cyclic <1>: Sexp Diary Entries.
+* diary-cyclic: Special Diary Entries.
+* diary-day-of-year: Sexp Diary Entries.
+* diary-float: Special Diary Entries.
+* diary-french-date: Sexp Diary Entries.
+* diary-hebrew-date: Sexp Diary Entries.
+* diary-islamic-date: Sexp Diary Entries.
+* diary-iso-date: Sexp Diary Entries.
+* diary-julian-date: Sexp Diary Entries.
+* diary-mail-entries: Diary Commands.
+* diary-mayan-date: Sexp Diary Entries.
+* diary-omer: Sexp Diary Entries.
+* diary-parasha: Sexp Diary Entries.
+* diary-phases-of-moon: Sexp Diary Entries.
+* diary-rosh-hodesh: Sexp Diary Entries.
+* diary-sabbath-candles: Sexp Diary Entries.
+* diary-sunrise-sunset: Sexp Diary Entries.
+* diary-yahrzeit: Sexp Diary Entries.
+* diff: Comparing Files.
+* diff-backup: Comparing Files.
+* digit-argument: Arguments.
+* dired: Dired Enter.
+* dired-other-window <1>: Pop Up Window.
+* dired-other-window: Dired Enter.
+* disable-command: Disabling.
+* disable-menu-item: Menu Customization.
+* disassemble: Compiling Libraries.
+* display-time: Mode Line.
+* dissociated-press: Dissociated Press.
+* do-auto-save: Auto Save Control.
* doctor: Total Frustration.
-* double slash in file name: Minibuffer File.
-* drastic changes: Reverting.
-* dribble file: Bugs.
-* early package hierarchies: Startup Paths.
-* echo area: Echo Area.
-* Edit menu <1>: Edit Menu.
-* Edit menu: Pull-down Menus.
-* editable fields (customization buffer): Customization Groups.
-* editing level, recursive <1>: Quitting.
-* editing level, recursive: Recursive Edit.
-* EDT: Emulation.
-* Eliza: Total Frustration.
-* Emacs initialization file: Init File.
-* Emacs-Lisp mode: Lisp Eval.
-* enabling menu items: Menu Customization.
-* encoding of characters: Mule.
-* End Macro Recording menu item: Edit Menu.
-* entering Emacs: Entering Emacs.
-* entering XEmacs: Entering Emacs.
-* environment: Single Shell.
-* error log: Compilation.
-* etags program: Create Tags Table.
-* Ethiopic calendar: Calendar Systems.
-* Execute Last Macro menu item: Edit Menu.
-* Exit Emacs menu item: File Menu.
-* exiting <1>: Recursive Edit.
-* exiting: Exiting.
-* expansion (of abbrevs): Abbrevs.
-* expression: Lists.
-* file dates: Interlocking.
-* file directory: ListDir.
-* File menu <1>: File Menu.
-* File menu: Pull-down Menus.
-* file names: File Names.
-* file protection: Interlocking.
-* files <1>: Visiting.
-* files <2>: Files.
-* files: Basic.
-* fill prefix: Fill Prefix.
-* filling: Filling.
-* Font menu item: Options Menu.
-* fonts and faces: Face Customization.
-* formfeed: Pages.
-* Fortran mode: Fortran.
-* frame: Frame.
-* French Revolutionary calendar: Calendar Systems.
-* function <1>: Key Bindings.
-* function: Commands.
-* General Public License: License.
-* global keymap: Keymaps.
-* global substitution: Replace.
-* graphic characters: Basic.
-* Greek: Mule.
-* Gregorian calendar: Other Calendars.
-* grinding: Grinding.
-* hardcopy: Hardcopy.
-* header (TeX mode): TeX Print.
-* headers (of mail message): Mail Headers.
-* heading lines (Outline mode): Outline Format.
-* Hebrew calendar: Calendar Systems.
-* help: Help.
-* Help menu <1>: Help Menu.
-* Help menu: Pull-down Menus.
-* hierarchies: Startup Paths.
-* history of commands: Repetition.
-* history of minibuffer input: Minibuffer History.
-* holiday forms: Holiday Customizing.
+* down-list: Lists.
+* downcase-region: Case.
+* downcase-word <1>: Case.
+* downcase-word: Fixing Case.
+* edit-abbrevs: Editing Abbrevs.
+* edit-abbrevs-redefine: Editing Abbrevs.
+* edit-options: Edit Options.
+* edit-picture: Picture.
+* edit-tab-stops <1>: Text Mode.
+* edit-tab-stops: Tab Stops.
+* edit-tab-stops-note-changes: Tab Stops.
+* edt-emulation-off: Emulation.
+* edt-emulation-on: Emulation.
+* electric-nroff-mode: Nroff Mode.
+* emacs-lisp-mode: Lisp Eval.
+* emacs-version: Bugs.
+* enable-command: Disabling.
+* enable-menu-item: Menu Customization.
+* end-kbd-macro: Basic Kbd Macro.
+* end-of-buffer: Basic.
+* end-of-defun: Defuns.
+* end-of-fortran-subprogram: Fortran Motion.
+* end-of-line: Basic.
+* enlarge-window: Change Window.
+* enlarge-window-horizontally: Change Window.
+* european-calendar: Date Formats.
+* eval-current-buffer: Lisp Eval.
+* eval-defun: Lisp Eval.
+* eval-expression: Lisp Eval.
+* eval-last-sexp: Lisp Eval.
+* eval-region: Lisp Eval.
+* exchange-point-and-mark: Setting Mark.
+* execute-extended-command: M-x.
+* exit-calendar: General Calendar.
+* exit-recursive-edit: Recursive Edit.
+* expand-abbrev: Expanding Abbrevs.
+* expand-region-abbrevs: Expanding Abbrevs.
+* fancy-diary-display: Fancy Diary Display.
+* fill-individual-paragraphs: Fill Prefix.
+* fill-paragraph: Fill Commands.
+* fill-region: Fill Commands.
+* fill-region-as-paragraph: Fill Commands.
+* find-alternate-file: Visiting.
+* find-file: Visiting.
+* find-file-other-frame <1>: Visiting.
+* find-file-other-frame: XEmacs under X.
+* find-file-other-window <1>: Pop Up Window.
+* find-file-other-window: Visiting.
+* find-tag: Find Tag.
+* find-tag-other-window <1>: Find Tag.
+* find-tag-other-window: Pop Up Window.
+* find-this-file: Visiting.
+* find-this-file-other-window: Visiting.
+* finder-by-keyword: Library Keywords.
+* fortran-column-ruler: Fortran Columns.
+* fortran-comment-region: Fortran Comments.
+* fortran-indent-line: ForIndent Commands.
+* fortran-indent-subprogram: ForIndent Commands.
+* fortran-mode: Fortran.
+* fortran-next-statement: Fortran Motion.
+* fortran-previous-statement: Fortran Motion.
+* fortran-split-line: ForIndent Commands.
+* fortran-window-create: Fortran Columns.
+* forward-char: Basic.
+* forward-list: Lists.
+* forward-page: Pages.
+* forward-paragraph: Paragraphs.
+* forward-sentence: Sentences.
+* forward-sexp: Lists.
+* forward-text-line: Nroff Mode.
+* forward-word: Words.
+* frame-configuration-to-register: RegConfig.
+* global-set-key <1>: Programmatic Rebinding.
+* global-set-key: Interactive Rebinding.
+* goto-char: Basic.
+* goto-line: Basic.
+* hanoi: Amusements.
+* help-command: Help.
+* help-for-help: Help.
+* help-with-tutorial <1>: Misc Help.
+* help-with-tutorial: Basic.
+* hide-body: Outline Visibility.
+* hide-entry: Outline Visibility.
+* hide-leaves: Outline Visibility.
+* hide-subtree: Outline Visibility.
* holidays: Holidays.
-* horizontal scrolling: Horizontal Scrolling.
-* ignoriginal: Dissociated Press.
-* indentation <1>: Comments.
-* indentation <2>: Grinding.
-* indentation: Indentation.
-* inferior process: Compilation.
-* init file: Init File.
-* input methods: Input Methods.
-* Insert File... menu item: File Menu.
-* insertion: Basic.
-* international scripts: Mule.
-* interval operator (in regexps): Etags Regexps.
-* invisible lines: Outline Mode.
-* IPA: Mule.
-* Islamic calendar: Calendar Systems.
-* ISO commercial calendar: Calendar Systems.
-* italic font: Face Customization.
-* Japanese: Mule.
-* Julian calendar: Calendar Systems.
-* Julian day numbers: Calendar Systems.
-* justification: Fill Commands.
-* key rebinding, permanent: Init File.
-* key rebinding, this session: Rebinding.
-* keyboard macros: Keyboard Macros.
-* keycode: Super and Hyper Keys.
-* keymap <1>: Keymaps.
-* keymap: Commands.
-* keystroke: Intro to Keystrokes.
-* keysym: Intro to Keystrokes.
-* keysyms: Super and Hyper Keys.
-* Kill Buffer menu item: File Menu.
-* kill ring: Yanking.
-* killing: Killing.
-* killing Emacs: Exiting.
-* Korean: Mule.
-* language environments: Language Environments.
-* last package hierarchies: Startup Paths.
-* late package hierarchies: Startup Paths.
-* LaTeX: TeX Mode.
-* libraries: Lisp Libraries.
-* license to copy XEmacs: License.
-* line number: Position Info.
-* Lisp: Programs.
-* Lisp mode: Program Modes.
-* list: Lists.
-* loading libraries: Loading.
-* loading Lisp code: Lisp Libraries.
-* local keymap: Keymaps.
-* local variables: Locals.
-* local variables in files: File Variables.
-* locking and version control: Concepts of VC.
-* log entry: Editing with VC.
-* mail <1>: Reading Mail.
+* include-other-diary-files: Included Diary Files.
+* increment-register: RegNumbers.
+* indent-c-exp: Multi-line Indent.
+* indent-for-comment: Comments.
+* indent-new-comment-line: Comments.
+* indent-region <1>: Multi-line Indent.
+* indent-region: Indentation Commands.
+* indent-relative: Indentation Commands.
+* indent-rigidly: Indentation Commands.
+* indent-sexp: Multi-line Indent.
+* indented-text-mode: Text Mode.
+* info: Misc Help.
+* Info-elisp-ref: Misc Help.
+* Info-goto-emacs-command-node: Misc Help.
+* insert-abbrevs: Saving Abbrevs.
+* insert-anniversary-diary-entry: Special Diary Entries.
+* insert-block-diary-entry: Special Diary Entries.
+* insert-cyclic-diary-entry: Special Diary Entries.
+* insert-diary-entry: Adding to Diary.
+* insert-file: Misc File Ops.
+* insert-hebrew-diary-entry: Hebrew/Islamic Entries.
+* insert-islamic-diary-entry: Hebrew/Islamic Entries.
+* insert-kbd-macro: Save Kbd Macro.
+* insert-monthly-diary-entry: Adding to Diary.
+* insert-monthly-hebrew-diary-entry: Hebrew/Islamic Entries.
+* insert-monthly-islamic-diary-entry: Hebrew/Islamic Entries.
+* insert-parentheses: Balanced Editing.
+* insert-register: RegText.
+* insert-weekly-diary-entry: Adding to Diary.
+* insert-yearly-diary-entry: Adding to Diary.
+* insert-yearly-hebrew-diary-entry: Hebrew/Islamic Entries.
+* insert-yearly-islamic-diary-entry: Hebrew/Islamic Entries.
+* interactive: M-x.
+* interrupt-shell-subjob: Shell Mode.
+* inverse-add-global-abbrev: Defining Abbrevs.
+* inverse-add-mode-abbrev: Defining Abbrevs.
+* invert-face: Faces.
+* isearch-abort: Incremental Search.
+* isearch-backward: Incremental Search.
+* isearch-backward-regexp: Regexp Search.
+* isearch-complete: Incremental Search.
+* isearch-delete-char: Incremental Search.
+* isearch-exit: Incremental Search.
+* isearch-forward: Incremental Search.
+* isearch-forward-regexp: Regexp Search.
+* isearch-quote-char: Incremental Search.
+* isearch-repeat-backward: Incremental Search.
+* isearch-repeat-forward: Incremental Search.
+* isearch-ring-advance: Incremental Search.
+* isearch-ring-retreat: Incremental Search.
+* isearch-yank-line: Incremental Search.
+* isearch-yank-word: Incremental Search.
+* jump-to-register <1>: Split Window.
+* jump-to-register: RegPos.
+* just-one-space: Killing.
+* kbd-macro-query: Kbd Macro Query.
+* kill-all-abbrevs: Defining Abbrevs.
+* kill-buffer: Kill Buffer.
+* kill-comment: Comments.
+* kill-compilation: Compilation.
+* kill-line: Killing.
+* kill-local-variable: Locals.
+* kill-output-from-shell: Shell Mode.
+* kill-rectangle: Rectangles.
+* kill-region: Killing.
+* kill-sentence <1>: Sentences.
+* kill-sentence: Killing.
+* kill-sexp <1>: Lists.
+* kill-sexp: Killing.
+* kill-some-buffers: Kill Buffer.
+* kill-word <1>: Words.
+* kill-word: Killing.
+* latex-mode: TeX Mode.
+* LaTeX-mode: TeX Mode.
+* lisp-complete-symbol: Lisp Completion.
+* lisp-indent-line: Basic Indent.
+* lisp-interaction-mode: Lisp Interaction.
+* lisp-mode: External Lisp.
+* lisp-send-defun: External Lisp.
+* list-abbrevs: Editing Abbrevs.
+* list-bookmarks: Bookmarks.
+* list-buffers: List Buffers.
+* list-calendar-holidays: Holidays.
+* list-coding-systems: Coding Systems.
+* list-command-history: Repetition.
+* list-directory: ListDir.
+* list-hebrew-diary-entries: Hebrew/Islamic Entries.
+* list-holidays: Holidays.
+* list-input-methods: Select Input Method.
+* list-islamic-diary-entries: Hebrew/Islamic Entries.
+* list-matching-lines: Other Repeating Search.
+* list-options: Edit Options.
+* list-tags: List Tags.
+* list-yahrzeit-dates: From Other Calendar.
+* load: Loading.
+* load-default-sounds: Audible Bell.
+* load-file: Loading.
+* load-library <1>: Loading.
+* load-library: Startup Paths.
+* load-sound-file: Audible Bell.
+* local-set-key: Interactive Rebinding.
+* local-unset-key: Interactive Rebinding.
+* locate-library: Loading.
+* lpr-buffer: Hardcopy.
+* lpr-region: Hardcopy.
* mail: Sending Mail.
-* major modes: Major Modes.
-* make: Compilation.
-* mark: Mark.
-* mark ring <1>: Mark and Region.
-* mark ring: Mark Ring.
-* Markov chain: Dissociated Press.
-* master file: Concepts of VC.
-* matching parentheses: Matching.
-* Mayan calendar: Calendar Systems.
-* Mayan calendar round: Mayan Calendar.
-* Mayan haab calendar: Mayan Calendar.
-* Mayan long count: Mayan Calendar.
-* Mayan tzolkin calendar: Mayan Calendar.
-* menus <1>: Change Window.
-* menus: Pull-down Menus.
-* message <1>: Reading Mail.
-* message: Sending Mail.
-* Meta: Words.
-* minibuffer <1>: Keymaps.
-* minibuffer <2>: M-x.
-* minibuffer: Minibuffer.
-* minibuffer history: Minibuffer History.
-* minor modes: Minor Modes.
-* mistakes, correcting <1>: Fixit.
-* mistakes, correcting: Undo.
-* mocklisp: Mocklisp.
-* mode hook: Program Modes.
-* mode line <1>: Minor Modes.
-* mode line: Mode Line.
-* mode, Term: Term Mode.
-* modified (buffer): Visiting.
-* modifier key: Intro to Keystrokes.
-* modifier mapping: Super and Hyper Keys.
-* moon, phases of: Lunar Phases.
-* mouse operations: Additional Mouse Operations.
-* mouse selection: Mouse Selection.
-* moving inside the calendar: Calendar Motion.
-* moving text: Yanking.
-* MULE: Mule.
-* multi-frame XEmacs: XEmacs under X.
-* multibyte characters: Mule.
-* named configurations (RCS): Snapshot Caveats.
-* narrowing: Narrowing.
-* New Frame menu item: File Menu.
+* mail-cc: Mail Mode.
+* mail-fill-yanked-message: Mail Mode.
+* mail-interactive-insert-alias: Mail Headers.
+* mail-other-window <1>: Sending Mail.
+* mail-other-window: Pop Up Window.
+* mail-send: Mail Mode.
+* mail-send-and-exit: Mail Mode.
+* mail-signature: Mail Mode.
+* mail-subject: Mail Mode.
+* mail-to: Mail Mode.
+* mail-yank-original: Mail Mode.
+* make-directory: File Names.
+* make-face-bold: Faces.
+* make-face-bold-italic: Faces.
+* make-face-italic: Faces.
+* make-face-larger: Faces.
+* make-face-smaller: Faces.
+* make-face-unbold: Faces.
+* make-face-unitalic: Faces.
+* make-frame: XEmacs under X.
+* make-local-variable: Locals.
+* make-obsolete: Compiling Libraries.
+* make-symbolic-link: Misc File Ops.
+* make-variable-buffer-local: Locals.
+* manual-entry: Documentation.
+* mark-beginning-of-buffer: Setting Mark.
+* mark-calendar-holidays: Holidays.
+* mark-defun <1>: Defuns.
+* mark-defun: Marking Objects.
+* mark-diary-entries: Diary Commands.
+* mark-end-of-buffer: Setting Mark.
+* mark-fortran-subprogram: Fortran Motion.
+* mark-hebrew-diary-entries: Hebrew/Islamic Entries.
+* mark-included-diary-files: Included Diary Files.
+* mark-islamic-diary-entries: Hebrew/Islamic Entries.
+* mark-page <1>: Pages.
+* mark-page: Marking Objects.
+* mark-paragraph <1>: Paragraphs.
+* mark-paragraph: Marking Objects.
+* mark-sexp <1>: Lists.
+* mark-sexp: Marking Objects.
+* mark-whole-buffer: Marking Objects.
+* mark-word <1>: Words.
+* mark-word: Marking Objects.
+* minibuffer-complete: Completion Example.
+* minibuffer-complete-word: Completion Commands.
+* modify-syntax-entry: Syntax Change.
+* mouse-choose-completion: Completion Commands.
+* mouse-del-char: Additional Mouse Operations.
+* mouse-delete-window: Additional Mouse Operations.
+* mouse-keep-one-window: Additional Mouse Operations.
+* mouse-kill-line: Additional Mouse Operations.
+* mouse-line-length: Additional Mouse Operations.
+* mouse-scroll: Additional Mouse Operations.
+* mouse-select: Additional Mouse Operations.
+* mouse-select-and-split: Additional Mouse Operations.
+* mouse-set-mark: Additional Mouse Operations.
+* mouse-set-point: Additional Mouse Operations.
+* mouse-track: Additional Mouse Operations.
+* mouse-track-adjust: Additional Mouse Operations.
+* mouse-track-and-copy-to-cutbuffer: Additional Mouse Operations.
+* mouse-track-delete-and-insert: Additional Mouse Operations.
+* move-over-close-and-reindent: Balanced Editing.
+* move-to-window-line: Basic.
+* name-last-kbd-macro: Save Kbd Macro.
+* narrow-to-region: Narrowing.
+* negative-argument: Arguments.
* newline: Basic.
-* non-incremental search: Non-Incremental Search.
-* nroff: Nroff Mode.
-* numeric arguments: Arguments.
-* omer count: Sexp Diary Entries.
-* Open File, New Frame... menu item: File Menu.
-* Open File... menu item: File Menu.
-* option <1>: Examining.
-* option: Variables.
-* Options menu <1>: Options Menu.
-* Options menu: Pull-down Menus.
-* other editors: Emulation.
-* outlines: Outline Mode.
-* outragedy: Dissociated Press.
-* Overstrike menu item: Options Menu.
-* Overwrite mode: Minor Modes.
-* package hierarchies: Startup Paths.
-* package path: Startup Paths.
-* packages: Packages.
-* page number: Position Info.
-* pages: Pages.
-* paragraphs: Paragraphs.
-* parasha, weekly: Sexp Diary Entries.
-* Paren Highlighting menu item: Options Menu.
-* parentheses: Matching.
-* Paste menu item: Edit Menu.
-* pasting: Yanking.
-* path: Startup Paths.
-* paths: Startup Paths.
-* per-buffer variables: Locals.
-* Persian calendar: Calendar Systems.
-* phases of the moon: Lunar Phases.
-* pictures: Picture.
-* point <1>: Basic.
-* point: Point.
-* pointer face: Mouse Selection.
-* pointer shapes: Mouse Selection.
-* prefix key sequence: Key Sequences.
-* presidentagon: Dissociated Press.
-* primary selections: X Selection Commands.
-* Print Buffer menu item: File Menu.
-* prompt: Minibuffer.
-* properbose: Dissociated Press.
-* Pull-down Menus <1>: Change Window.
-* Pull-down Menus: Pull-down Menus.
-* query replace: Query Replace.
-* quitting: Quitting.
-* quitting (in search): Incremental Search.
-* quoting: Basic.
-* random sentences: CONX.
-* RCS: Concepts of VC.
-* Read Only menu item: Options Menu.
-* read-only buffer: Misc Buffer.
-* rebinding keys, permanently: Init File.
-* rebinding keys, this session: Rebinding.
-* rectangle <1>: Rectangles in Picture.
-* rectangle: RegRect.
-* rectangles: Rectangles.
-* recursive editing level <1>: Quitting.
-* recursive editing level: Recursive Edit.
-* redefining keys: Key Bindings Using Strings.
-* regexp: Regexp Search.
-* region <1>: Case.
-* region: Mark.
-* registered file: Concepts of VC.
-* registers: Registers.
-* regular expression: Regexp Search.
-* regular packages: Package Terminology.
-* removing directories: File Names.
-* replacement: Replace.
-* restriction: Narrowing.
-* Revert Buffer menu item: File Menu.
-* root of a hierarchy: Startup Paths.
-* rosh hodesh: Sexp Diary Entries.
-* Russian: Mule.
-* Save Buffer As ... menu item: File Menu.
-* Save Buffer menu item: File Menu.
-* Save Options: Options Menu.
-* saving: Visiting.
-* saving option value: Changing an Option.
-* SCCS: Concepts of VC.
-* Scheme mode: Program Modes.
-* scrolling: Scrolling.
-* scrolling in the calendar: Scroll Calendar.
-* searching: Search.
-* selected buffer: Buffers.
-* selected window: Basic Window.
-* selective display: Outline Mode.
-* self-documentation: Help.
-* sentences: Sentences.
-* setting option value: Changing an Option.
-* setting variables: Examining.
-* sexp: Lists.
-* sexp diary entries: Sexp Diary Entries.
-* shell commands: Shell.
-* Shell mode: Shell Mode.
-* shift modifer: Representing Keystrokes.
-* shrinking XEmacs frame: Exiting.
-* simultaneous editing: Interlocking.
-* single-file packages: Package Terminology.
-* site-specific directories: Startup Paths.
-* Size menu item: Options Menu.
-* slashes repeated in file name: Minibuffer File.
-* snapshots and version control: Snapshots.
-* sorting: Sorting.
-* sorting diary entries: Fancy Diary Display.
-* source packages: Package Terminology.
-* spelling: Spelling.
-* Split Frame: File Menu.
-* Start Macro Recording menu item: Edit Menu.
-* startup paths: Startup Paths.
-* string substitution: Replace.
-* subshell: Shell.
-* subtree (Outline mode): Outline Visibility.
-* sunrise and sunset: Sunrise/Sunset.
-* suspending: Exiting.
-* switching buffers: Select Buffer.
-* Syntax Highlighting menu item: Options Menu.
-* syntax table <1>: Syntax.
-* syntax table: Words.
-* tags table: Tags.
-* Teach Extended Commands menu item: Options Menu.
-* techniquitous: Dissociated Press.
-* television: Appending Kills.
-* Term mode: Term Mode.
-* termscript file: Bugs.
-* TeX: TeX Mode.
-* text: Text.
-* Text mode: Text Mode.
-* Tools menu <1>: Tools Menu.
-* Tools menu: Pull-down Menus.
-* top level: Mode Line.
-* transposition <1>: Lists.
-* transposition <2>: Words.
-* transposition: Transpose.
-* truncation: Continuation Lines.
-* typos: Fixit.
-* Un-split (Keep Others): File Menu.
-* Un-split (Keep This): File Menu.
+* newline-and-indent: Basic Indent.
+* next-complex-command: Repetition.
+* next-error: Compilation.
+* next-history-element: Minibuffer History.
+* next-line: Basic.
+* next-list-mode-item: Completion Commands.
+* next-matching-history-element: Minibuffer History.
+* not-modified: Saving.
+* nroff-mode: Nroff Mode.
+* number-to-register: RegNumbers.
+* occur: Other Repeating Search.
+* open-dribble-file: Bugs.
+* open-line: Blank Lines.
+* open-rectangle: Rectangles.
+* open-termscript: Bugs.
+* other-window: Other Window.
+* other-window-any-frame: Other Window.
+* outline-backward-same-level: Outline Motion.
+* outline-forward-same-level: Outline Motion.
+* outline-next-visible-heading: Outline Motion.
+* outline-previous-visible-heading: Outline Motion.
+* outline-up-heading: Outline Motion.
+* overwrite-mode: Minor Modes.
+* phases-of-moon: Lunar Phases.
+* picture-backward-clear-column: Basic Picture.
+* picture-backward-column: Basic Picture.
+* picture-clear-column: Basic Picture.
+* picture-clear-line: Basic Picture.
+* picture-clear-rectangle: Rectangles in Picture.
+* picture-clear-rectangle-to-register: Rectangles in Picture.
+* picture-forward-column: Basic Picture.
+* picture-motion: Insert in Picture.
+* picture-motion-reverse: Insert in Picture.
+* picture-move-down: Basic Picture.
+* picture-move-up: Basic Picture.
+* picture-movement-down: Insert in Picture.
+* picture-movement-left: Insert in Picture.
+* picture-movement-ne: Insert in Picture.
+* picture-movement-nw: Insert in Picture.
+* picture-movement-right: Insert in Picture.
+* picture-movement-se: Insert in Picture.
+* picture-movement-sw: Insert in Picture.
+* picture-movement-up: Insert in Picture.
+* picture-newline: Basic Picture.
+* picture-open-line: Basic Picture.
+* picture-set-tab-stops: Tabs in Picture.
+* picture-tab: Tabs in Picture.
+* picture-tab-search: Tabs in Picture.
+* picture-yank-rectangle: Rectangles in Picture.
+* picture-yank-rectangle-from-register: Rectangles in Picture.
+* plain-TeX-mode: TeX Mode.
+* plain-tex-mode: TeX Mode.
+* play-sound: Audible Bell.
+* point-to-register: RegPos.
+* prefer-coding-system: Recognize Coding.
+* prepend-to-buffer: Accumulating Text.
+* previous-complex-command: Repetition.
+* previous-history-element: Minibuffer History.
+* previous-line: Basic.
+* previous-list-mode-item: Completion Commands.
+* previous-matching-history-element: Minibuffer History.
+* print-buffer: Hardcopy.
+* print-diary-entries <1>: Diary Customizing.
+* print-diary-entries: Diary Commands.
+* print-region: Hardcopy.
+* quail-set-keyboard-layout: Select Input Method.
+* query-replace: Query Replace.
+* query-replace-regexp: Query Replace.
+* quietly-read-abbrev-file: Saving Abbrevs.
+* quit-shell-subjob: Shell Mode.
+* quoted-insert: Basic.
+* re-search-backward: Regexp Search.
+* re-search-forward: Regexp Search.
+* read-abbrev-file: Saving Abbrevs.
+* read-key-sequence: Representing Keystrokes.
+* recenter <1>: Scrolling.
+* recenter: Basic.
+* recover-file: Recover.
+* redraw-calendar: General Calendar.
+* relabel-menu-item: Menu Customization.
+* remove-directory: File Names.
+* rename-buffer: Misc Buffer.
+* rename-file: Misc File Ops.
+* repeat-complex-command: Repetition.
+* replace-regexp: Unconditional Replace.
+* replace-string: Unconditional Replace.
+* revert-buffer: Reverting.
+* run-lisp: External Lisp.
+* save-buffer: Saving.
+* save-buffers-kill-emacs: Exiting.
+* save-some-buffers: Saving.
+* scroll-calendar-left: Scroll Calendar.
+* scroll-calendar-left-three-months: Scroll Calendar.
+* scroll-calendar-right: Scroll Calendar.
+* scroll-calendar-right-three-months: Scroll Calendar.
+* scroll-down: Scrolling.
+* scroll-left: Horizontal Scrolling.
+* scroll-other-window <1>: General Calendar.
+* scroll-other-window: Other Window.
+* scroll-right: Horizontal Scrolling.
+* scroll-up: Scrolling.
+* search-backward: Non-Incremental Search.
+* search-forward: Non-Incremental Search.
+* select-input-method: Select Input Method.
+* self-insert: Basic.
+* send-shell-input: Shell Mode.
+* set-buffer-file-coding-system: Specify Coding.
+* set-buffer-process-coding-system: Specify Coding.
+* set-comment-column: Comments.
+* set-default-file-modes: Interlocking.
+* set-face-background: Faces.
+* set-face-background-pixmap: Faces.
+* set-face-font: Faces.
+* set-face-foreground: Faces.
+* set-face-underline-p: Faces.
+* set-fill-column: Fill Commands.
+* set-fill-prefix: Fill Prefix.
+* set-gnu-bindings: Emulation.
+* set-goal-column: Basic.
+* set-gosmacs-bindings: Emulation.
+* set-keyboard-coding-system: Specify Coding.
+* set-language-environment: Language Environments.
+* set-mark-command: Setting Mark.
+* set-selective-display: Selective Display.
+* set-terminal-coding-system: Specify Coding.
+* set-variable: Examining.
+* set-visited-file-name: Saving.
+* setq-default: Locals.
+* shell: Interactive Shell.
+* shell-command: Single Shell.
+* shell-command-on-region: Single Shell.
+* shell-send-eof: Shell Mode.
+* show-all: Outline Visibility.
+* show-all-diary-entries: Diary Commands.
+* show-branches: Outline Visibility.
+* show-children: Outline Visibility.
+* show-entry: Outline Visibility.
+* show-output-from-shell: Shell Mode.
+* show-subtree: Outline Visibility.
+* simple-diary-display: Fancy Diary Display.
+* sort-columns: Sorting.
+* sort-diary-entries: Fancy Diary Display.
+* sort-fields: Sorting.
+* sort-lines: Sorting.
+* sort-numeric-fields: Sorting.
+* sort-pages: Sorting.
+* sort-paragraphs: Sorting.
+* spell-buffer: Spelling.
+* spell-region: Spelling.
+* spell-string: Spelling.
+* spell-word: Spelling.
+* split-line: Indentation Commands.
+* split-window-horizontally: Split Window.
+* split-window-vertically: Split Window.
+* start-kbd-macro: Basic Kbd Macro.
+* stop-shell-subjob: Shell Mode.
+* substitute-key-definition: Interactive Rebinding.
+* sunrise-sunset: Sunrise/Sunset.
+* suspend-emacs: Exiting.
+* switch-to-buffer: Select Buffer.
+* switch-to-buffer-other-frame <1>: Select Buffer.
+* switch-to-buffer-other-frame: XEmacs under X.
+* switch-to-buffer-other-window <1>: Pop Up Window.
+* switch-to-buffer-other-window: Select Buffer.
+* switch-to-other-buffer: Select Buffer.
+* tab-to-tab-stop <1>: Text Mode.
+* tab-to-tab-stop: Tab Stops.
+* tabify: Just Spaces.
+* tags-apropos: List Tags.
+* tags-loop-continue: Tags Search.
+* tags-query-replace: Tags Search.
+* tags-search: Tags Search.
+* term: Terminal emulator.
+* term-line-mode: Term Mode.
+* term-pager-toggle: Paging in Term.
+* tex-buffer: TeX Print.
+* tex-close-latex-block: TeX Editing.
+* tex-insert-braces: TeX Editing.
+* tex-insert-quote: TeX Editing.
+* tex-kill-job: TeX Print.
+* tex-mode: TeX Mode.
+* TeX-mode: TeX Mode.
+* tex-print: TeX Print.
+* tex-recenter-output-buffer: TeX Print.
+* tex-region: TeX Print.
+* tex-show-print-queue: TeX Print.
+* tex-terminate-paragraph: TeX Editing.
+* text-mode: Text Mode.
+* toggle-input-method: Select Input Method.
+* toggle-read-only: Misc Buffer.
+* top-level <1>: Quitting.
+* top-level: Recursive Edit.
+* transpose-chars <1>: Transpose.
+* transpose-chars: Basic.
+* transpose-lines: Transpose.
+* transpose-sexps <1>: Lists.
+* transpose-sexps: Transpose.
+* transpose-words <1>: Words.
+* transpose-words: Transpose.
* undo: Undo.
-* Undo menu item: Edit Menu.
-* variable: Variables.
-* variables: Commands.
-* version control: Version Control.
-* version-specific directories: Startup Paths.
-* vi: Emulation.
-* viewing: Misc File Ops.
-* Viper: Emulation.
-* visiting: Visiting.
-* visiting files: Visiting.
-* weeks, which day they start on: Move to Beginning or End.
-* Weight menu item: Options Menu.
-* widening: Narrowing.
-* window: Frame.
-* windows: Windows.
-* Windows menu: Change Window.
-* word search: Word Search.
-* words <1>: Case.
-* words <2>: Words.
-* words: Fixing Case.
-* work file: Concepts of VC.
-* X resources: X Resources.
-* yahrzeits <1>: Sexp Diary Entries.
-* yahrzeits: From Other Calendar.
-* yanking: Yanking.
-
+* unexpand-abbrev: Expanding Abbrevs.
+* universal-argument: Arguments.
+* universal-coding-system-argument: Specify Coding.
+* untabify: Just Spaces.
+* up-list: TeX Editing.
+* upcase-region: Case.
+* upcase-word <1>: Case.
+* upcase-word: Fixing Case.
+* validate-tex-buffer: TeX Editing.
+* vc-cancel-version: Editing with VC.
+* vc-create-snapshot: Making Snapshots.
+* vc-diff: Old Versions.
+* vc-directory: VC Status.
+* vc-insert-headers: Version Headers.
+* vc-next-action: Editing with VC.
+* vc-print-log: VC Status.
+* vc-register: Editing with VC.
+* vc-rename-file: Renaming and VC.
+* vc-retrieve-snapshot: Making Snapshots.
+* vc-revert-buffer: Editing with VC.
+* vc-update-change-log: Change Logs and VC.
+* vc-version-other-window: Old Versions.
+* view-buffer: Misc Buffer.
+* view-diary-entries: Diary Commands.
+* view-emacs-news: Misc Help.
+* view-file: Misc File Ops.
+* view-hello-file: Mule Intro.
+* view-lossage: Misc Help.
+* view-register: Registers.
+* visit-tags-table: Select Tags Table.
+* what-cursor-position: Position Info.
+* what-line: Position Info.
+* what-page: Position Info.
+* where-is: Name Help.
+* widen: Narrowing.
+* widget-backward: Changing an Option.
+* widget-complete: Changing an Option.
+* widget-forward: Changing an Option.
+* window-configuration-to-register <1>: Split Window.
+* window-configuration-to-register: RegConfig.
+* word-search-backward: Word Search.
+* word-search-forward: Word Search.
+* write-abbrev-file: Saving Abbrevs.
+* write-file: Saving.
+* x-copy-primary-selection: X Selection Commands.
+* x-create-frame: X Resources.
+* x-delete-primary-selection: X Selection Commands.
+* x-insert-selection: X Selection Commands.
+* x-kill-primary-selection: X Selection Commands.
+* x-mouse-kill: X Selection Commands.
+* x-own-secondary-selection: X Selection Commands.
+* x-own-selection: X Selection Commands.
+* x-set-point-and-insert-selection: X Selection Commands.
+* xemacs-local-faq: Misc Help.
+* Yank: Kill Ring.
+* yank-pop: Earlier Kills.
+* yank-rectangle: Rectangles.
+* yow: Amusements.
+* zap-to-char: Killing.
+* zmacs-activate-region: Active Regions.
+* zmacs-deactivate-region: Active Regions.
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Additional Mouse Operations, Next: Killing, Prev: Mouse Selection, Up: Top
+
+Additional Mouse Operations
+===========================
+
+ XEmacs also provides the following mouse functions. Most of these
+are not bound to mouse gestures by default, but they are provided for
+your customization pleasure. For example, if you wanted `shift-left'
+(that is, holding down the <Shift> key and clicking the left mouse
+button) to delete the character at which you are pointing, then you
+could do this:
+
+ (global-set-key '(shift button1) 'mouse-del-char)
+
+`mouse-del-char'
+ Delete the character pointed to by the mouse.
+
+`mouse-delete-window'
+ Delete the Emacs window that the mouse is on.
+
+`mouse-keep-one-window'
+ Select the Emacs window that the mouse is on, then delete all other
+ windows on this frame.
+
+`mouse-kill-line'
+ Kill the line pointed to by the mouse.
+
+`mouse-line-length'
+ Print the length of the line indicated by the pointer.
+
+`mouse-scroll'
+ Scroll point to the mouse position.
+
+`mouse-select'
+ Select the Emacs window the mouse is on.
+
+`mouse-select-and-split'
+ Select the Emacs window mouse is on, then split it vertically in
+ half.
+
+`mouse-set-mark'
+ Select the Emacs window the mouse is on and set the mark at the
+ mouse position. Display the cursor at that position for a second.
+
+`mouse-set-point'
+ Select the Emacs window that the mouse is on and move point to the
+ mouse position.
+
+`mouse-track'
+ Make a selection with the mouse. This is the default binding of
+ the left mouse button (<button1>).
+
+`mouse-track-adjust'
+ Extend the existing selection. This is the default binding of
+ <Shift-button1>.
+
+`mouse-track-and-copy-to-cutbuffer'
+ Make a selection like `mouse-track', but also copy it to the cut
+ buffer.
+
+`mouse-track-delete-and-insert'
+ Make a selection with the mouse and insert it at point. This is
+ the default binding of <control-shift-button1>.
+
+`mouse-track-insert'
+ Make a selection with the mouse and insert it at point. This is
+ the default binding of <control-button1>.
+
+`mouse-window-to-region'
+ Narrow a window to the region between the cursor and the mouse
+ pointer.
+
+ The `M-x mouse-track' command should be bound to a mouse button. If
+you click-and-drag, the selection is set to the region between the
+point of the initial click and the point at which you release the
+button. These positions do not need to be ordered.
+
+ If you click-and-release without moving the mouse, the point is
+moved, and the selection is disowned (there will be no selection
+owner.) The mark will be set to the previous position of point.
+
+ If you double-click, the selection will extend by symbols instead of
+by characters. If you triple-click, the selection will extend by lines.
+
+ If you drag the mouse off the top or bottom of the window, you can
+select pieces of text that are larger than the visible part of the
+buffer; the buffer will scroll as necessary.
+
+ The selected text becomes the current X selection, and is also
+copied to the top of the kill ring. Point will be left at the position
+at which you released the button and the mark will be left at the
+initial click position. Bind a mouse click to
+`mouse-track-and-copy-to-cutbuffer' to copy selections to the cut
+buffer. (See also the `mouse-track-adjust' command, on
+`Shift-button1'.)
+
+ The `M-x mouse-track-adjust' command should be bound to a mouse
+button. The selection will be enlarged or shrunk so that the point of
+the mouse click is one of its endpoints. This is only meaningful after
+the `mouse-track' command (<button1>) has been executed.
+
+ The `M-x mouse-track-delete-and-insert' command is exactly the same
+as the `mouse-track' command on <button1>, except that point is not
+moved; the selected text is immediately inserted after being selected;
+and the text of the selection is deleted.
+
+ The `M-x mouse-track-insert' command is exactly the same as the
+`mouse-track' command on <button1>, except that point is not moved; the
+selected text is immediately inserted after being selected; and the
+selection is immediately disowned afterwards.
+
+\1f
File: xemacs.info, Node: Killing, Next: Yanking, Prev: Additional Mouse Operations, Up: Top
Deletion and Killing
`scroll-conservatively' to a small value, which will have the result of
overriding the redisplay preemption.
-\1f
-File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display
-
-Horizontal Scrolling
-====================
-
-`C-x <'
- Scroll text in current window to the left (`scroll-left').
-
-`C-x >'
- Scroll to the right (`scroll-right').
-
- The text in a window can also be scrolled horizontally. This means
-that each line of text is shifted sideways in the window, and one or
-more characters at the beginning of each line are not displayed at all.
-When a window has been scrolled horizontally in this way, text lines
-are truncated rather than continued (*note Continuation Lines::), with
-a `$' appearing in the first column when there is text truncated to the
-left, and in the last column when there is text truncated to the right.
-
- The command `C-x <' (`scroll-left') scrolls the selected window to
-the left by N columns with argument N. With no argument, it scrolls by
-almost the full width of the window (two columns less, to be precise).
-`C-x >' (`scroll-right') scrolls similarly to the right. The window
-cannot be scrolled any farther to the right once it is displaying
-normally (with each line starting at the window's left margin);
-attempting to do so has no effect.
-
-\1f
-File: xemacs.info, Node: Selective Display, Next: Display Vars, Prev: Display, Up: Display
-
-Selective Display
-=================
-
- XEmacs can hide lines indented more than a certain number of columns
-(you specify how many columns). This allows you to get an overview of
-a part of a program.
-
- To hide lines, type `C-x $' (`set-selective-display') with a numeric
-argument N. (*Note Arguments::, for information on giving the
-argument.) Lines with at least N columns of indentation disappear from
-the screen. The only indication of their presence are three dots
-(`...'), which appear at the end of each visible line that is followed
-by one or more invisible ones.
-
- The invisible lines are still present in the buffer, and most editing
-commands see them as usual, so it is very easy to put point in the
-middle of invisible text. When this happens, the cursor appears at the
-end of the previous line, after the three dots. If point is at the end
-of the visible line, before the newline that ends it, the cursor
-appears before the three dots.
-
- The commands `C-n' and `C-p' move across the invisible lines as if
-they were not there.
-
- To make everything visible again, type `C-x $' with no argument.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display
+
+Horizontal Scrolling
+====================
+
+`C-x <'
+ Scroll text in current window to the left (`scroll-left').
+
+`C-x >'
+ Scroll to the right (`scroll-right').
+
+ The text in a window can also be scrolled horizontally. This means
+that each line of text is shifted sideways in the window, and one or
+more characters at the beginning of each line are not displayed at all.
+When a window has been scrolled horizontally in this way, text lines
+are truncated rather than continued (*note Continuation Lines::), with
+a `$' appearing in the first column when there is text truncated to the
+left, and in the last column when there is text truncated to the right.
+
+ The command `C-x <' (`scroll-left') scrolls the selected window to
+the left by N columns with argument N. With no argument, it scrolls by
+almost the full width of the window (two columns less, to be precise).
+`C-x >' (`scroll-right') scrolls similarly to the right. The window
+cannot be scrolled any farther to the right once it is displaying
+normally (with each line starting at the window's left margin);
+attempting to do so has no effect.
+
+\1f
+File: xemacs.info, Node: Selective Display, Next: Display Vars, Prev: Display, Up: Display
+
+Selective Display
+=================
+
+ XEmacs can hide lines indented more than a certain number of columns
+(you specify how many columns). This allows you to get an overview of
+a part of a program.
+
+ To hide lines, type `C-x $' (`set-selective-display') with a numeric
+argument N. (*Note Arguments::, for information on giving the
+argument.) Lines with at least N columns of indentation disappear from
+the screen. The only indication of their presence are three dots
+(`...'), which appear at the end of each visible line that is followed
+by one or more invisible ones.
+
+ The invisible lines are still present in the buffer, and most editing
+commands see them as usual, so it is very easy to put point in the
+middle of invisible text. When this happens, the cursor appears at the
+end of the previous line, after the three dots. If point is at the end
+of the visible line, before the newline that ends it, the cursor
+appears before the three dots.
+
+ The commands `C-n' and `C-p' move across the invisible lines as if
+they were not there.
+
+ To make everything visible again, type `C-x $' with no argument.
+
+\1f
File: xemacs.info, Node: Display Vars, Prev: Selective Display, Up: Display
Variables Controlling Display
the files in it.
* Misc File Ops:: Other things you can do on files.
-\1f
-File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
-
-File Names
-==========
-
- Most Emacs commands that operate on a file require you to specify the
-file name. (Saving and reverting are exceptions; the buffer knows which
-file name to use for them.) File names are specified in the minibuffer
-(*note Minibuffer::). "Completion" is available, to make it easier to
-specify long file names. *Note Completion::.
-
- There is always a "default file name" which is used if you enter an
-empty argument by typing just <RET>. Normally the default file name is
-the name of the file visited in the current buffer; this makes it easy
-to operate on that file with any of the Emacs file commands.
-
- Each buffer has a default directory, normally the same as the
-directory of the file visited in that buffer. When Emacs reads a file
-name, the default directory is used if you do not specify a directory.
-If you specify a directory in a relative fashion, with a name that does
-not start with a slash, it is interpreted with respect to the default
-directory. The default directory of the current buffer is kept in the
-variable `default-directory', which has a separate value in every
-buffer. The value of the variable should end with a slash.
-
- For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
-the default directory is `/u/rms/gnu/'. If you type just `foo', which
-does not specify a directory, it is short for `/u/rms/gnu/foo'.
-`../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
-the filename `/u/rms/gnu/new/foo'.
-
- The variable `default-directory-alist' takes an alist of major modes
-and their opinions on `default-directory' as a Lisp expression to
-evaluate. A resulting value of `nil' is ignored in favor of
-`default-directory'.
-
- You can create a new directory with the function `make-directory',
-which takes as an argument a file name string. The current directory is
-displayed in the minibuffer when the function is called; you can delete
-the old directory name and supply a new directory name. For example, if
-the current directory is `/u/rms/gnu', you can delete `gnu' and type
-`oryx' and <RET> to create `/u/rms/oryx'. Removing a directory is
-similar to creating one. To remove a directory, use
-`remove-directory'; it takes one argument, a file name string.
-
- The command `M-x pwd' prints the current buffer's default directory,
-and the command `M-x cd' sets it (to a value read using the
-minibuffer). A buffer's default directory changes only when the `cd'
-command is used. A file-visiting buffer's default directory is
-initialized to the directory of the file that is visited there. If a
-buffer is created with `C-x b', its default directory is copied from
-that of the buffer that was current at the time.
-
- The default directory name actually appears in the minibuffer when
-the minibuffer becomes active to read a file name. This serves two
-purposes: it shows you what the default is, so that you can type a
-relative file name and know with certainty what it will mean, and it
-allows you to edit the default to specify a different directory. To
-inhibit the insertion of the default directory, set the variable
-`insert-default-directory' to `nil'.
-
- Note that it is legitimate to type an absolute file name after you
-enter the minibuffer, ignoring the presence of the default directory
-name. The final minibuffer contents may look invalid, but that is not
-so. *Note Minibuffer File::.
-
- `$' in a file name is used to substitute environment variables. For
-example, if you have used the shell command `setenv FOO rms/hacks' to
-set up an environment variable named `FOO', then you can use
-`/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
-`/u/rms/hacks/test.c'. The environment variable name consists of all
-the alphanumeric characters after the `$'; alternatively, it may be
-enclosed in braces after the `$'. Note that the `setenv' command
-affects Emacs only if done before Emacs is started.
-
- To access a file with `$' in its name, type `$$'. This pair is
-converted to a single `$' at the same time variable substitution is
-performed for single `$'. The Lisp function that performs the
-substitution is called `substitute-in-file-name'. The substitution is
-performed only on filenames read as such using the minibuffer.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
+
+File Names
+==========
+
+ Most Emacs commands that operate on a file require you to specify the
+file name. (Saving and reverting are exceptions; the buffer knows which
+file name to use for them.) File names are specified in the minibuffer
+(*note Minibuffer::). "Completion" is available, to make it easier to
+specify long file names. *Note Completion::.
+
+ There is always a "default file name" which is used if you enter an
+empty argument by typing just <RET>. Normally the default file name is
+the name of the file visited in the current buffer; this makes it easy
+to operate on that file with any of the Emacs file commands.
+
+ Each buffer has a default directory, normally the same as the
+directory of the file visited in that buffer. When Emacs reads a file
+name, the default directory is used if you do not specify a directory.
+If you specify a directory in a relative fashion, with a name that does
+not start with a slash, it is interpreted with respect to the default
+directory. The default directory of the current buffer is kept in the
+variable `default-directory', which has a separate value in every
+buffer. The value of the variable should end with a slash.
+
+ For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
+the default directory is `/u/rms/gnu/'. If you type just `foo', which
+does not specify a directory, it is short for `/u/rms/gnu/foo'.
+`../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
+the filename `/u/rms/gnu/new/foo'.
+
+ The variable `default-directory-alist' takes an alist of major modes
+and their opinions on `default-directory' as a Lisp expression to
+evaluate. A resulting value of `nil' is ignored in favor of
+`default-directory'.
+
+ You can create a new directory with the function `make-directory',
+which takes as an argument a file name string. The current directory is
+displayed in the minibuffer when the function is called; you can delete
+the old directory name and supply a new directory name. For example, if
+the current directory is `/u/rms/gnu', you can delete `gnu' and type
+`oryx' and <RET> to create `/u/rms/oryx'. Removing a directory is
+similar to creating one. To remove a directory, use
+`remove-directory'; it takes one argument, a file name string.
+
+ The command `M-x pwd' prints the current buffer's default directory,
+and the command `M-x cd' sets it (to a value read using the
+minibuffer). A buffer's default directory changes only when the `cd'
+command is used. A file-visiting buffer's default directory is
+initialized to the directory of the file that is visited there. If a
+buffer is created with `C-x b', its default directory is copied from
+that of the buffer that was current at the time.
+
+ The default directory name actually appears in the minibuffer when
+the minibuffer becomes active to read a file name. This serves two
+purposes: it shows you what the default is, so that you can type a
+relative file name and know with certainty what it will mean, and it
+allows you to edit the default to specify a different directory. To
+inhibit the insertion of the default directory, set the variable
+`insert-default-directory' to `nil'.
+
+ Note that it is legitimate to type an absolute file name after you
+enter the minibuffer, ignoring the presence of the default directory
+name. The final minibuffer contents may look invalid, but that is not
+so. *Note Minibuffer File::.
+
+ `$' in a file name is used to substitute environment variables. For
+example, if you have used the shell command `setenv FOO rms/hacks' to
+set up an environment variable named `FOO', then you can use
+`/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
+`/u/rms/hacks/test.c'. The environment variable name consists of all
+the alphanumeric characters after the `$'; alternatively, it may be
+enclosed in braces after the `$'. Note that the `setenv' command
+affects Emacs only if done before Emacs is started.
+
+ To access a file with `$' in its name, type `$$'. This pair is
+converted to a single `$' at the same time variable substitution is
+performed for single `$'. The Lisp function that performs the
+substitution is called `substitute-in-file-name'. The substitution is
+performed only on filenames read as such using the minibuffer.
+
+\1f
File: xemacs.info, Node: Visiting, Next: Saving, Prev: File Names, Up: Files
Visiting Files
log the change with an entry beginning with `#' to avoid putting such
trivia into `ChangeLog'.
-\1f
-File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control
-
-Examining And Comparing Old Versions
-------------------------------------
-
-`C-x v ~ VERSION <RET>'
- Examine version VERSION of the visited file, in a buffer of its
- own (`vc-version-other-window').
-
-`C-x v ='
- Compare the current buffer contents with the latest checked-in
- version of the file.
-
-`C-u C-x v = FILE <RET> OLDVERS <RET> NEWVERS <RET>'
- Compare the specified two versions of FILE.
-
- You can examine any version of a file by first visiting it, and then
-using `C-x v ~ VERSION <RET>' (`vc-version-other-window'). This puts
-the text of version VERSION in a file named `FILENAME.~VERSION~', then
-visits it in a separate window.
-
- To compare two versions of a file, use the command `C-x v ='
-(`vc-diff').
-
- Plain `C-x v =' compares the current buffer contents (saving them in
-the file if necessary) with the last checked-in version of the file.
-With a prefix argument, `C-x v =' reads a file name and two version
-numbers, then compares those versions of the specified file.
-
- If you supply a directory name instead of the name of a work file,
-this command compares the two specified versions of all registered files
-in that directory and its subdirectories. You can also specify a
-snapshot name (*note Snapshots::) instead of one or both version
-numbers.
-
- You can specify a checked-in version by its number; you can specify
-the most recent checked-in version with an empty version number.
-
- This command works by running the `vcdiff' utility, getting the
-options from the variable `diff-switches'. It displays the output in a
-special buffer in another window. Unlike the `M-x diff' command, `C-x
-v =' does not try to find the changes in the old and new versions.
-This is because one or both versions normally do not exist as files.
-They exist only in the records of the master file. *Note Comparing
-Files::, for more information about `M-x diff'.
-
-\1f
-File: xemacs.info, Node: VC Status, Next: Renaming and VC, Prev: Old Versions, Up: Version Control
-
-VC Status Commands
-------------------
-
- To view the detailed version control status and history of a file,
-type `C-x v l' (`vc-print-log'). It displays the history of changes to
-the current file, including the text of the log entries. The output
-appears in a separate window.
-
- When you are working on a large program, it's often useful to find
-all the files that are currently locked, or all the files maintained in
-version control at all. You can use `C-x v d' (`vc-directory') to show
-all the locked files in or beneath the current directory. This
-includes all files that are locked by any user. `C-u C-x v d' lists
-all files in or beneath the current directory that are maintained with
-version control.
-
- The list of files is displayed as a buffer that uses an augmented
-Dired mode. The names of the users locking various files are shown (in
-parentheses) in place of the owner and group. All the normal Dired
-commands work in this buffer. Most interactive VC commands work also,
-and apply to the file name on the current line.
-
- The `C-x v v' command (`vc-next-action'), when used in the augmented
-Dired buffer, operates on all the marked files (or the file on the
-current line). If it operates on more than one file, it handles each
-file according to its current state; thus, it may check out one file
-and check in another (because it is already checked out). If it has to
-check in any files, it reads a single log entry, then uses that text
-for all the files being checked in. This can be convenient for
-registering or checking in several files at once, as part of the same
-change.
-
-\1f
-File: xemacs.info, Node: Renaming and VC, Next: Snapshots, Prev: VC Status, Up: Version Control
-
-Renaming VC Work Files and Master Files
----------------------------------------
-
- When you rename a registered file, you must also rename its master
-file correspondingly to get proper results. Use `vc-rename-file' to
-rename the source file as you specify, and rename its master file
-accordingly. It also updates any snapshots (*note Snapshots::) that
-mention the file, so that they use the new name; despite this, the
-snapshot thus modified may not completely work (*note Snapshot
-Caveats::).
-
- You cannot use `vc-rename-file' on a file that is locked by someone
-else.
-
-\1f
-File: xemacs.info, Node: Snapshots, Next: Version Headers, Prev: Renaming and VC, Up: Version Control
-
-Snapshots
----------
-
- A "snapshot" is a named set of file versions (one for each
-registered file) that you can treat as a unit. One important kind of
-snapshot is a "release", a (theoretically) stable version of the system
-that is ready for distribution to users.
-
-* Menu:
-
-* Making Snapshots:: The snapshot facilities.
-* Snapshot Caveats:: Things to be careful of when using snapshots.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control
+
+Examining And Comparing Old Versions
+------------------------------------
+
+`C-x v ~ VERSION <RET>'
+ Examine version VERSION of the visited file, in a buffer of its
+ own (`vc-version-other-window').
+
+`C-x v ='
+ Compare the current buffer contents with the latest checked-in
+ version of the file.
+
+`C-u C-x v = FILE <RET> OLDVERS <RET> NEWVERS <RET>'
+ Compare the specified two versions of FILE.
+
+ You can examine any version of a file by first visiting it, and then
+using `C-x v ~ VERSION <RET>' (`vc-version-other-window'). This puts
+the text of version VERSION in a file named `FILENAME.~VERSION~', then
+visits it in a separate window.
+
+ To compare two versions of a file, use the command `C-x v ='
+(`vc-diff').
+
+ Plain `C-x v =' compares the current buffer contents (saving them in
+the file if necessary) with the last checked-in version of the file.
+With a prefix argument, `C-x v =' reads a file name and two version
+numbers, then compares those versions of the specified file.
+
+ If you supply a directory name instead of the name of a work file,
+this command compares the two specified versions of all registered files
+in that directory and its subdirectories. You can also specify a
+snapshot name (*note Snapshots::) instead of one or both version
+numbers.
+
+ You can specify a checked-in version by its number; you can specify
+the most recent checked-in version with an empty version number.
+
+ This command works by running the `vcdiff' utility, getting the
+options from the variable `diff-switches'. It displays the output in a
+special buffer in another window. Unlike the `M-x diff' command, `C-x
+v =' does not try to find the changes in the old and new versions.
+This is because one or both versions normally do not exist as files.
+They exist only in the records of the master file. *Note Comparing
+Files::, for more information about `M-x diff'.
+
+\1f
+File: xemacs.info, Node: VC Status, Next: Renaming and VC, Prev: Old Versions, Up: Version Control
+
+VC Status Commands
+------------------
+
+ To view the detailed version control status and history of a file,
+type `C-x v l' (`vc-print-log'). It displays the history of changes to
+the current file, including the text of the log entries. The output
+appears in a separate window.
+
+ When you are working on a large program, it's often useful to find
+all the files that are currently locked, or all the files maintained in
+version control at all. You can use `C-x v d' (`vc-directory') to show
+all the locked files in or beneath the current directory. This
+includes all files that are locked by any user. `C-u C-x v d' lists
+all files in or beneath the current directory that are maintained with
+version control.
+
+ The list of files is displayed as a buffer that uses an augmented
+Dired mode. The names of the users locking various files are shown (in
+parentheses) in place of the owner and group. All the normal Dired
+commands work in this buffer. Most interactive VC commands work also,
+and apply to the file name on the current line.
+
+ The `C-x v v' command (`vc-next-action'), when used in the augmented
+Dired buffer, operates on all the marked files (or the file on the
+current line). If it operates on more than one file, it handles each
+file according to its current state; thus, it may check out one file
+and check in another (because it is already checked out). If it has to
+check in any files, it reads a single log entry, then uses that text
+for all the files being checked in. This can be convenient for
+registering or checking in several files at once, as part of the same
+change.
+
+\1f
+File: xemacs.info, Node: Renaming and VC, Next: Snapshots, Prev: VC Status, Up: Version Control
+
+Renaming VC Work Files and Master Files
+---------------------------------------
+
+ When you rename a registered file, you must also rename its master
+file correspondingly to get proper results. Use `vc-rename-file' to
+rename the source file as you specify, and rename its master file
+accordingly. It also updates any snapshots (*note Snapshots::) that
+mention the file, so that they use the new name; despite this, the
+snapshot thus modified may not completely work (*note Snapshot
+Caveats::).
+
+ You cannot use `vc-rename-file' on a file that is locked by someone
+else.
+
+\1f
+File: xemacs.info, Node: Snapshots, Next: Version Headers, Prev: Renaming and VC, Up: Version Control
+
+Snapshots
+---------
+
+ A "snapshot" is a named set of file versions (one for each
+registered file) that you can treat as a unit. One important kind of
+snapshot is a "release", a (theoretically) stable version of the system
+that is ready for distribution to users.
+
+* Menu:
+
+* Making Snapshots:: The snapshot facilities.
+* Snapshot Caveats:: Things to be careful of when using snapshots.
+
+\1f
File: xemacs.info, Node: Making Snapshots, Next: Snapshot Caveats, Prev: Snapshots, Up: Snapshots
Making and Using Snapshots
* Recognize Coding:: How XEmacs figures out which conversion to use.
* Specify Coding:: Various ways to choose which conversion to use.
-\1f
-File: xemacs.info, Node: Mule Intro, Next: Language Environments, Prev: Mule, Up: Mule
-
-Introduction to world scripts
-=============================
-
- The users of these scripts have established many more-or-less
-standard coding systems for storing files. XEmacs translates between
-the internal character encoding and various other coding systems when
-reading and writing files, when exchanging data with subprocesses, and
-(in some cases) in the `C-q' command (see below).
-
- The command `C-h h' (`view-hello-file') displays the file
-`etc/HELLO', which shows how to say "hello" in many languages. This
-illustrates various scripts.
-
- Keyboards, even in the countries where these character sets are used,
-generally don't have keys for all the characters in them. So XEmacs
-supports various "input methods", typically one for each script or
-language, to make it convenient to type them.
-
- The prefix key `C-x <RET>' is used for commands that pertain to
-world scripts, coding systems, and input methods.
-
-\1f
-File: xemacs.info, Node: Language Environments, Next: Input Methods, Prev: Mule Intro, Up: Mule
-
-Language Environments
-=====================
-
- All supported character sets are supported in XEmacs buffers if it is
-compile with mule; there is no need to select a particular language in
-order to display its characters in an XEmacs buffer. However, it is
-important to select a "language environment" in order to set various
-defaults. The language environment really represents a choice of
-preferred script (more or less) rather that a choice of language.
-
- The language environment controls which coding systems to recognize
-when reading text (*note Recognize Coding::). This applies to files,
-incoming mail, netnews, and any other text you read into XEmacs. It may
-also specify the default coding system to use when you create a file.
-Each language environment also specifies a default input method.
-
- The command to select a language environment is `M-x
-set-language-environment'. It makes no difference which buffer is
-current when you use this command, because the effects apply globally to
-the XEmacs session. The supported language environments include:
-
- Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ISO, English,
- Ethiopic, Greek, Japanese, Korean, Latin-1, Latin-2, Latin-3,
- Latin-4, Latin-5.
-
- Some operating systems let you specify the language you are using by
-setting locale environment variables. XEmacs handles one common special
-case of this: if your locale name for character types contains the
-string `8859-N', XEmacs automatically selects the corresponding
-language environment.
-
- To display information about the effects of a certain language
-environment LANG-ENV, use the command `C-h L LANG-ENV <RET>'
-(`describe-language-environment'). This tells you which languages this
-language environment is useful for, and lists the character sets,
-coding systems, and input methods that go with it. It also shows some
-sample text to illustrate scripts used in this language environment.
-By default, this command describes the chosen language environment.
-
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Mule Intro, Next: Language Environments, Prev: Mule, Up: Mule
+
+Introduction to world scripts
+=============================
+
+ The users of these scripts have established many more-or-less
+standard coding systems for storing files. XEmacs translates between
+the internal character encoding and various other coding systems when
+reading and writing files, when exchanging data with subprocesses, and
+(in some cases) in the `C-q' command (see below).
+
+ The command `C-h h' (`view-hello-file') displays the file
+`etc/HELLO', which shows how to say "hello" in many languages. This
+illustrates various scripts.
+
+ Keyboards, even in the countries where these character sets are used,
+generally don't have keys for all the characters in them. So XEmacs
+supports various "input methods", typically one for each script or
+language, to make it convenient to type them.
+
+ The prefix key `C-x <RET>' is used for commands that pertain to
+world scripts, coding systems, and input methods.
+
+\1f
+File: xemacs.info, Node: Language Environments, Next: Input Methods, Prev: Mule Intro, Up: Mule
+
+Language Environments
+=====================
+
+ All supported character sets are supported in XEmacs buffers if it is
+compile with mule; there is no need to select a particular language in
+order to display its characters in an XEmacs buffer. However, it is
+important to select a "language environment" in order to set various
+defaults. The language environment really represents a choice of
+preferred script (more or less) rather that a choice of language.
+
+ The language environment controls which coding systems to recognize
+when reading text (*note Recognize Coding::). This applies to files,
+incoming mail, netnews, and any other text you read into XEmacs. It may
+also specify the default coding system to use when you create a file.
+Each language environment also specifies a default input method.
+
+ The command to select a language environment is `M-x
+set-language-environment'. It makes no difference which buffer is
+current when you use this command, because the effects apply globally to
+the XEmacs session. The supported language environments include:
+
+ Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ISO, English,
+ Ethiopic, Greek, Japanese, Korean, Latin-1, Latin-2, Latin-3,
+ Latin-4, Latin-5.
+
+ Some operating systems let you specify the language you are using by
+setting locale environment variables. XEmacs handles one common special
+case of this: if your locale name for character types contains the
+string `8859-N', XEmacs automatically selects the corresponding
+language environment.
+
+ To display information about the effects of a certain language
+environment LANG-ENV, use the command `C-h L LANG-ENV <RET>'
+(`describe-language-environment'). This tells you which languages this
+language environment is useful for, and lists the character sets,
+coding systems, and input methods that go with it. It also shows some
+sample text to illustrate scripts used in this language environment.
+By default, this command describes the chosen language environment.
+
+\1f
File: xemacs.info, Node: Input Methods, Next: Select Input Method, Prev: Language Environments, Up: Mule
Input Methods
* Motion: Outline Motion. Special commands for moving through outlines.
* Visibility: Outline Visibility. Commands to control what is visible.
-\1f
-File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
-
-Format of Outlines
-..................
-
- Outline mode assumes that the lines in the buffer are of two types:
-"heading lines" and "body lines". A heading line represents a topic in
-the outline. Heading lines start with one or more stars; the number of
-stars determines the depth of the heading in the outline structure.
-Thus, a heading line with one star is a major topic; all the heading
-lines with two stars between it and the next one-star heading are its
-subtopics; and so on. Any line that is not a heading line is a body
-line. Body lines belong to the preceding heading line. Here is an
-example:
-
- * Food
-
- This is the body,
- which says something about the topic of food.
-
- ** Delicious Food
-
- This is the body of the second-level header.
-
- ** Distasteful Food
-
- This could have
- a body too, with
- several lines.
-
- *** Dormitory Food
-
- * Shelter
-
- A second first-level topic with its header line.
-
- A heading line together with all following body lines is called
-collectively an "entry". A heading line together with all following
-deeper heading lines and their body lines is called a "subtree".
-
- You can customize the criterion for distinguishing heading lines by
-setting the variable `outline-regexp'. Any line whose beginning has a
-match for this regexp is considered a heading line. Matches that start
-within a line (not at the beginning) do not count. The length of the
-matching text determines the level of the heading; longer matches make
-a more deeply nested level. Thus, for example, if a text formatter has
-commands `@chapter', `@section' and `@subsection' to divide the
-document into chapters and sections, you can make those lines count as
-heading lines by setting `outline-regexp' to
-`"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words
-`chapter' and `section' are the same length, but by defining the regexp
-to match only `chap' we ensure that the length of the text matched on a
-chapter heading is shorter, so that Outline mode will know that
-sections are contained in chapters. This works as long as no other
-command starts with `@chap'.
-
- Outline mode makes a line invisible by changing the newline before it
-into an ASCII Control-M (code 015). Most editing commands that work on
-lines treat an invisible line as part of the previous line because,
-strictly speaking, it is part of that line, since there is no longer a
-newline in between. When you save the file in Outline mode, Control-M
-characters are saved as newlines, so the invisible lines become ordinary
-lines in the file. Saving does not change the visibility status of a
-line inside Emacs.
-
projects / chise / xemacs-chise.git- / commitdiff