From 57ebfe1aee090631a0d07fcc35b8e5dfac098719 Mon Sep 17 00:00:00 2001 From: tomo Date: Wed, 10 May 2000 03:32:04 +0000 Subject: [PATCH] XEmacs 21.2.32 "Kastor & Polydeukes". --- info/internals.info-3 | 215 +-- info/internals.info-4 | 79 + info/internals.info-5 | 69 +- info/lispref.info-15 | 167 +- info/lispref.info-16 | 261 +-- info/lispref.info-17 | 176 +- info/lispref.info-18 | 51 + info/lispref.info-20 | 731 ++++---- info/lispref.info-21 | 745 ++++---- info/lispref.info-22 | 750 +++++---- info/lispref.info-23 | 719 ++++---- info/lispref.info-24 | 809 ++++----- info/lispref.info-25 | 968 +++++------ info/lispref.info-26 | 1136 ++++++------- info/lispref.info-27 | 1228 +++++++------- info/lispref.info-28 | 1198 ++++++------- info/lispref.info-29 | 1065 +++++++----- info/lispref.info-30 | 931 +++++----- info/lispref.info-31 | 982 +++++------ info/lispref.info-32 | 1060 ++++++------ info/lispref.info-33 | 1162 ++++++------- info/lispref.info-34 | 1216 ++++++------- info/lispref.info-35 | 1055 +++++++----- info/lispref.info-36 | 962 ++++++----- info/lispref.info-37 | 867 +++++----- info/lispref.info-38 | 839 ++++----- info/lispref.info-39 | 897 +++++----- info/lispref.info-40 | 1106 ++++++------ info/lispref.info-41 | 2060 +++++++++++----------- info/lispref.info-42 | 1997 +++++++++++----------- info/lispref.info-43 | 2432 ++++++++++++-------------- info/lispref.info-44 | 4401 ++++++++++++------------------------------------ info/xemacs-faq.info-3 | 6 +- info/xemacs-faq.info-5 | 31 +- info/xemacs.info-10 | 216 +-- info/xemacs.info-11 | 285 ++-- info/xemacs.info-12 | 304 ++-- info/xemacs.info-13 | 356 ++-- info/xemacs.info-14 | 458 ++--- info/xemacs.info-15 | 514 +++--- info/xemacs.info-16 | 527 +++--- info/xemacs.info-17 | 597 ++++--- info/xemacs.info-18 | 1080 ++++-------- info/xemacs.info-19 | 1721 +++++++++---------- info/xemacs.info-20 | 1694 +++++++++++-------- info/xemacs.info-21 | 1497 ++++++++-------- info/xemacs.info-5 | 169 +- info/xemacs.info-6 | 139 +- info/xemacs.info-7 | 197 +-- info/xemacs.info-8 | 181 +- info/xemacs.info-9 | 132 +- 51 files changed, 19726 insertions(+), 22712 deletions(-) diff --git a/info/internals.info-3 b/info/internals.info-3 index b65ca3b..2025e00 100644 --- a/info/internals.info-3 +++ b/info/internals.info-3 @@ -286,13 +286,17 @@ File: internals.info, Node: Techniques for XEmacs Developers, Prev: Coding for 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 @@ -328,14 +332,105 @@ out where the cycles are going. Specific projects: 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: @@ -358,15 +453,6 @@ you can try to improve the test suite in `tests/automated'. * Header files should _not_ include `' 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: @@ -375,17 +461,19 @@ 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'  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 @@ -1123,82 +1211,3 @@ TTY. These files provide some miscellaneous TTY-output functions and should probably be merged into `redisplay-tty.c'. - -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. - diff --git a/info/internals.info-4 b/info/internals.info-4 index dc56007..26d82a9 100644 --- a/info/internals.info-4 +++ b/info/internals.info-4 @@ -38,6 +38,85 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + 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 diff --git a/info/internals.info-5 b/info/internals.info-5 index 5b53574..d2c73c5 100644 --- a/info/internals.info-5 +++ b/info/internals.info-5 @@ -286,7 +286,9 @@ lrecords 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, @@ -319,20 +321,21 @@ allocation function for each lrecord type. 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 @@ -346,21 +349,20 @@ for keeping allocation statistics.) 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 @@ -559,10 +561,9 @@ system, when memory gets to 75%, 85%, and 95% full. (On some systems, 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 diff --git a/info/lispref.info-15 b/info/lispref.info-15 index 18fc766..9818e56 100644 --- a/info/lispref.info-15 +++ b/info/lispref.info-15 @@ -735,20 +735,23 @@ Defining Commands::. 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. @@ -784,22 +787,29 @@ Reading Lisp Objects with 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: @@ -811,22 +821,33 @@ minibuffer. The user can type 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 (`"') @@ -1131,7 +1152,7 @@ minibuffer with completion. 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::. @@ -1168,121 +1189,3 @@ minibuffer with completion. `minibuffer-completion-confirm'. For more information about them, see *Note Completion Commands::. - -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' - - - `minibuffer-complete-word' - - - `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' - - - `minibuffer-complete-word' - - - `minibuffer-complete' - - `C-j' - `minibuffer-complete-and-exit' - - - `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. - diff --git a/info/lispref.info-16 b/info/lispref.info-16 index 1ba0d48..e9b7573 100644 --- a/info/lispref.info-16 +++ b/info/lispref.info-16 @@ -50,6 +50,124 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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' + + + `minibuffer-complete-word' + + + `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' + + + `minibuffer-complete-word' + + + `minibuffer-complete' + + `C-j' + `minibuffer-complete-and-exit' + + + `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. + + File: lispref.info, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion High-Level Completion Functions @@ -94,13 +212,19 @@ Defining Commands::. ;; The user types `minibuffer.t '. => "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, @@ -123,10 +247,16 @@ Defining Commands::. (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, @@ -160,7 +290,7 @@ a file name. It provides special features including automatic insertion 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 . @@ -1084,128 +1214,3 @@ Examples of Using `interactive' (three-b "*scratch*" "declarations.texi" "*mail*") => nil - -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) - diff --git a/info/lispref.info-17 b/info/lispref.info-17 index 1ad01db..f9926db 100644 --- a/info/lispref.info-17 +++ b/info/lispref.info-17 @@ -50,6 +50,131 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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) + + File: lispref.info, Node: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop Information from the Command Loop @@ -1185,54 +1310,3 @@ input. (discard-input)) => nil - -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. - diff --git a/info/lispref.info-18 b/info/lispref.info-18 index 860dab1..47f826c 100644 --- a/info/lispref.info-18 +++ b/info/lispref.info-18 @@ -50,6 +50,57 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + File: lispref.info, Node: Quitting, Next: Prefix Command Arguments, Prev: Waiting, Up: Command Loop Quitting diff --git a/info/lispref.info-20 b/info/lispref.info-20 index d1c1da4..504086a 100644 --- a/info/lispref.info-20 +++ b/info/lispref.info-20 @@ -342,7 +342,7 @@ Dialog Box Functions using a dialog box.  -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 ******* @@ -675,9 +675,378 @@ expanded to take up the slack. startup.  -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. + + +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. + + +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'. + + +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::). + + +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. + + +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. + + +File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets + +Buffer Tabs +=========== + + Not documented yet. + + +File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets + +Progress Bars +============= + + Not documented yet. + + +File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top + +Scrollbars ********** Not yet documented. @@ -847,359 +1216,3 @@ Keymaps::, and *Note Syntax Tables::. * Modeline Format:: Customizing the text that appears in the modeline. * Hooks:: How to use hooks; how to write code that provides hooks. - -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 - (`eval-print-last-sexp'), (`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. - - -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 `\', 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::. - - -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. - diff --git a/info/lispref.info-21 b/info/lispref.info-21 index c8cee5a..fb2f5da 100644 --- a/info/lispref.info-21 +++ b/info/lispref.info-21 @@ -50,6 +50,362 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 + (`eval-print-last-sexp'), (`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. + + +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 `\', 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::. + + +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. + + File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes How XEmacs Chooses a Major Mode @@ -761,392 +1117,3 @@ obsolete, since you can get the same results with the variables The value of `global-mode-string'. Currently, only `display-time' modifies the value of `global-mode-string'. - -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. - - -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. - - -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'. - - -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. - diff --git a/info/lispref.info-22 b/info/lispref.info-22 index b11b775..b42187d 100644 --- a/info/lispref.info-22 +++ b/info/lispref.info-22 @@ -50,6 +50,395 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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. + + +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'. + + +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. + + File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation Substituting Key Bindings in Documentation @@ -748,364 +1137,3 @@ copying the contents of the buffer into the file. add newlines at all. `nil' is the default value, but a few major modes set it to `t' in particular buffers. - -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::. - - -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. - - -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'. - - -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. - - -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::. - - -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). - - -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. - diff --git a/info/lispref.info-23 b/info/lispref.info-23 index 6f4fb86..35745c5 100644 --- a/info/lispref.info-23 +++ b/info/lispref.info-23 @@ -50,6 +50,367 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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::. + + +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. + + +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'. + + +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. + + +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::. + + +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). + + +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. + + File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files Other Information about Files @@ -898,361 +1259,3 @@ directories. `delete-file' does not work for files that are directories; you must use `delete-directory' in that case. - -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. - - -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:: - - -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. - - -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. - - -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. - - -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 - 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 - 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 - 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 - 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. - diff --git a/info/lispref.info-24 b/info/lispref.info-24 index fd5a9c1..5eeea30 100644 --- a/info/lispref.info-24 +++ b/info/lispref.info-24 @@ -50,6 +50,364 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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:: + + +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. + + +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. + + +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. + + +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 + 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 + 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 + 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 + 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. + + File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files Files and MS-DOS @@ -732,454 +1090,3 @@ Buffers and Windows::. - Function: bufferp object This function returns `t' if OBJECT is a buffer, `nil' otherwise. - -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) - => # - - - 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. - - -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")) - => # - (kill-buffer foo) - => nil - (buffer-name foo) - => nil - foo - => # - - - 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")) - => # - (get-buffer b) - => # - (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::. - - -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") - => # - - 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. - - -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. - - -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::. - - -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. - diff --git a/info/lispref.info-25 b/info/lispref.info-25 index 7329de7..feffc1f 100644 --- a/info/lispref.info-25 +++ b/info/lispref.info-25 @@ -50,6 +50,457 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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) + => # + + - 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. + + +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")) + => # + (kill-buffer foo) + => nil + (buffer-name foo) + => nil + foo + => # + + - 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")) + => # + (get-buffer b) + => # + (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::. + + +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") + => # + + 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. + + +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. + + +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::. + + +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. + + File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers The Buffer List @@ -695,520 +1146,3 @@ among all the siblings.) This function always returns `nil'. - -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) - => # - - - 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. - - -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) - => # - (next-window (selected-window)) - => # - (next-window (next-window (selected-window))) - => # - - - 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. - - -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) - => # - - - 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. - - -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'. - - -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. - diff --git a/info/lispref.info-26 b/info/lispref.info-26 index 235bc4a..61c2e38 100644 --- a/info/lispref.info-26 +++ b/info/lispref.info-26 @@ -50,6 +50,523 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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) + => # + + - 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. + + +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) + => # + (next-window (selected-window)) + => # + (next-window (next-window (selected-window))) + => # + + - 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. + + +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) + => # + + - 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. + + +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'. + + +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. + + File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows Windows and Point @@ -577,622 +1094,3 @@ are allowed in XEmacs. bottom)', all relative to `(0,0)' at the top left corner of the window. - -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. - - -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) - => # - (setq w (selected-window)) - => # - (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. - - -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. - - -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. - - -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). - - -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. - - -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. - - -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. - - -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'.) - - -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. - - -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::. - - -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. - diff --git a/info/lispref.info-27 b/info/lispref.info-27 index 68b995e..bfdf263 100644 --- a/info/lispref.info-27 +++ b/info/lispref.info-27 @@ -50,6 +50,635 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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) + => # + (setq w (selected-window)) + => # + (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. + + +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. + + +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. + + +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). + + +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. + + +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. + + +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. + + +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'.) + + +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. + + +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::. + + +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. + + File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames Finding All Frames @@ -612,602 +1241,3 @@ written in terms of `make-device'. This function returns the X display which DEVICE is connected to, if DEVICE is an X device. - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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! - - -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. - - -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. - - -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. - - -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. - diff --git a/info/lispref.info-28 b/info/lispref.info-28 index dc9450b..51c114c 100644 --- a/info/lispref.info-28 +++ b/info/lispref.info-28 @@ -50,6 +50,605 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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! + + +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. + + +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. + + +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. + + +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. + + File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions Excursions @@ -587,602 +1186,3 @@ Emacs. - Function: move-marker marker position &optional buffer This is another name for `set-marker'. - -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 '. 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)) - => # - (set-marker m 100) - => # - (mark-marker) - => # - - 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 - => (# - # - ...) - - - 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. - - -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. - - -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. - - -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. - - -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 - " - - -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 - - -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 ---------- - diff --git a/info/lispref.info-29 b/info/lispref.info-29 index 7d0ee18..07d9698 100644 --- a/info/lispref.info-29 +++ b/info/lispref.info-29 @@ -50,6 +50,605 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 '. 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)) + => # + (set-marker m 100) + => # + (mark-marker) + => # + + 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 + => (# + # + ...) + + - 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. + + +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. + + +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. + + +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. + + +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 + " + + +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 + + +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 ---------- + + File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text User-Level Insertion Commands @@ -528,469 +1127,3 @@ Emacs version 18. The normal use of this hook is to set the X server's primary selection to the newly killed text. - -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. - - -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. - - -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. - - -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. - - -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, indents to this column. This variable - automatically becomes buffer-local when set in any fashion. - - -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. - diff --git a/info/lispref.info-30 b/info/lispref.info-30 index bfb3ed5..5ca45e7 100644 --- a/info/lispref.info-30 +++ b/info/lispref.info-30 @@ -50,6 +50,472 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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. + + +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. + + +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. + + +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, indents to this column. This variable + automatically becomes buffer-local when set in any fashion. + + +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. + + File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text Sorting Text @@ -708,468 +1174,3 @@ along with the characters; this includes such diverse functions as * Saving Properties:: Saving text properties in files, and reading them back. - -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 - - -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. - - -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. - - -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::. - - -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. - - -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 ---------- - - -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. - - -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. - diff --git a/info/lispref.info-31 b/info/lispref.info-31 index 138661a..ad8a2e8 100644 --- a/info/lispref.info-31 +++ b/info/lispref.info-31 @@ -50,6 +50,471 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 + + +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. + + +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. + + +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::. + + +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. + + +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 ---------- + + +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. + + +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. + + File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text Change Hooks @@ -692,520 +1157,3 @@ functions, an `invalid-regexp' error is signaled. (re-search-forward (concat "\\s-" (regexp-quote string) "\\s-")) - -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. - - -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 - - -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. - - -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. - - -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. - - -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.) - - -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. - diff --git a/info/lispref.info-32 b/info/lispref.info-32 index 3173f9f..fd9588b 100644 --- a/info/lispref.info-32 +++ b/info/lispref.info-32 @@ -50,6 +50,523 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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 + + +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. + + +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. + + +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. + + +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.) + + +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. + + File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data Accessing the Entire Match Data @@ -688,546 +1205,3 @@ version 18 or earlier. flag. Optional argument BUFFER defaults to the current buffer if omitted. - -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. - - -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.) - - -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. - - -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. - - -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)'. - - -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. - - -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. - - -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'. - - -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")))) - - -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. - diff --git a/info/lispref.info-33 b/info/lispref.info-33 index 2e32df8..785b693 100644 --- a/info/lispref.info-33 +++ b/info/lispref.info-33 @@ -50,6 +50,549 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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.) + + +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. + + +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. + + +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)'. + + +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. + + +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. + + +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'. + + +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")))) + + +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. + + File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top Extents @@ -474,622 +1017,3 @@ the following function may be more convenient than `map-extents'. This function returns T if `map-extents' would visit EXTENT if called with the given arguments. - -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. - - -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::. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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 - - -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. - diff --git a/info/lispref.info-34 b/info/lispref.info-34 index 65fa87c..fb64927 100644 --- a/info/lispref.info-34 +++ b/info/lispref.info-34 @@ -50,6 +50,625 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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::. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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 + + +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. + + File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers How a Specifier Is Instanced @@ -449,600 +1068,3 @@ Adding specifications to a Specifier If NOERROR is `nil', signal an error if the spec-list is invalid; otherwise return `t'. - -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'. - - -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. - - -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. - - -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)) - => # - - (specifier-specs sp) - => ((# (nil . "forest green")) - (# (nil . "hot pink")) - (# (nil . "puke orange") - (nil . "moccasin")) - (# (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-frame (get-buffer-window "*scratch*")) - => # - (specifier-instance sp (get-buffer-window "*scratch*")) - => # - - 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 `(# . "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 `(# . "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. - - -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'. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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::). - diff --git a/info/lispref.info-35 b/info/lispref.info-35 index 2db233e..83b50f0 100644 --- a/info/lispref.info-35 +++ b/info/lispref.info-35 @@ -50,6 +50,603 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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'. + + +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. + + +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. + + +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)) + => # + + (specifier-specs sp) + => ((# (nil . "forest green")) + (# (nil . "hot pink")) + (# (nil . "puke orange") + (nil . "moccasin")) + (# (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-frame (get-buffer-window "*scratch*")) + => # + (specifier-instance sp (get-buffer-window "*scratch*")) + => # + + 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 `(# . "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 `(# . "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. + + +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'. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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::). + + File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces Face Properties @@ -536,461 +1133,3 @@ Color Specifiers - Function: color-specifier-p object This function returns non-`nil' if OBJECT is a color specifier. - -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)) - => # - - 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. - - -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) - - -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) - - -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. - - -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. - - -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'. - - -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. - - -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. - - -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. - - -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. - diff --git a/info/lispref.info-36 b/info/lispref.info-36 index 26a4393..473b7f6 100644 --- a/info/lispref.info-36 +++ b/info/lispref.info-36 @@ -50,6 +50,464 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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)) + => # + + 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. + + +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) + + +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) + + +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. + + +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. + + +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'. + + +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. + + +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. + + +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. + + +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. + + File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images Image Specifiers @@ -109,78 +567,78 @@ instance types. 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 `'] 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 @@ -189,63 +647,62 @@ keyword-value pairs. The "format" field should be a symbol, one of 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 @@ -704,418 +1161,3 @@ can work with annotations without knowing how extents work. * Annotation Hooks:: Hooks called at certain times during an annotation's lifetime. - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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.) - - -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::. - diff --git a/info/lispref.info-37 b/info/lispref.info-37 index bb9e02e..7a64c76 100644 --- a/info/lispref.info-37 +++ b/info/lispref.info-37 @@ -50,6 +50,421 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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.) + + +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::. + + File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display The Echo Area @@ -826,455 +1241,3 @@ a vector Display according to the standard interpretation (*note Usual Display::). - -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-name )' - - 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. - - -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. - - -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'. - - -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. - - -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'. - - -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. - - -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. - - -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. - - -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:: - - -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'. - diff --git a/info/lispref.info-38 b/info/lispref.info-38 index cfb33fd..2ac7f8e 100644 --- a/info/lispref.info-38 +++ b/info/lispref.info-38 @@ -50,6 +50,458 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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-name )' + + 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. + + +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. + + +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'. + + +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. + + +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'. + + +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. + + +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. + + +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. + + +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:: + + +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'. + + File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases Working With a Database @@ -791,390 +1243,3 @@ discarded. * Accepting Output:: Explicitly permitting subprocess output. Waiting for subprocess output. - -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")) - => # - - - 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*") - => # - - Killing the process's buffer deletes the process, which kills the - subprocess with a `SIGHUP' signal (*note Signals to Processes::). - - -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 - ") - - -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. - - -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: # had the event `killed' - => # - - - 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. - - -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. - - -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::. - - -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). - diff --git a/info/lispref.info-39 b/info/lispref.info-39 index 90be6be..9a6e077 100644 --- a/info/lispref.info-39 +++ b/info/lispref.info-39 @@ -50,6 +50,393 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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")) + => # + + - 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*") + => # + + Killing the process's buffer deletes the process, which kills the + subprocess with a `SIGHUP' signal (*note Signals to Processes::). + + +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 + ") + + +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. + + +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: # had the event `killed' + => # + + - 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. + + +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. + + +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::. + + +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). + + File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top Operating System Interface @@ -806,513 +1193,3 @@ Titles::). 3. Return "C:\", as a fallback, but issue a warning. - -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::). - - -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. - - -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'.) - - -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. - - -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'. - - -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 ` 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" ` O P' to `[pf1]' in `function-key-map', - when using a VT100. - - Thus, typing `C-c ' sends the character sequence `C-c O - P'; later the function `read-key-sequence' translates this back - into `C-c ', 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. - - -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::). - diff --git a/info/lispref.info-40 b/info/lispref.info-40 index 3a42e0c..69a170a 100644 --- a/info/lispref.info-40 +++ b/info/lispref.info-40 @@ -50,6 +50,516 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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::). + + +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. + + +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'.) + + +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. + + +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'. + + +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 ` 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" ` O P' to `[pf1]' in `function-key-map', + when using a VT100. + + Thus, typing `C-c ' sends the character sequence `C-c O + P'; later the function `read-key-sequence' translates this back + into `C-c ', 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. + + +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::). + + File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface Terminal Output @@ -643,599 +1153,3 @@ in the first argument of the message. (let ((m (make-tooltalk-message random-query-message))) (send-tooltalk-message m)) - -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_' 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. - - -File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support - -Receiving Messages -================== - -* Menu: - -* Example of Receiving Messages:: -* Elisp Interface for Receiving Messages:: - - -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)) - - -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. - - -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 - - -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 () - - * University of Michigan's LDAP 3.3 - () - - * LDAP SDK 1.0 from Netscape Corp. () - - 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. - - -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 - - -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. - - -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'. - - -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):: - - -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 - - -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 - - -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. - - -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: - - ( ) - - `' is an attribute name such as `cn' for Common Name, `o' for -Organization, etc... - - `' 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 `(=*' 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'. - - -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. - - -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. - - -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:: - diff --git a/info/lispref.info-41 b/info/lispref.info-41 index 571b28f..417c4eb 100644 --- a/info/lispref.info-41 +++ b/info/lispref.info-41 @@ -50,1160 +50,1202 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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_' 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.  -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'. - - -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::  -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") + +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.  -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  -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 - -File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top + * OpenLDAP 1.0.3 () -MULE -**** + * University of Michigan's LDAP 3.3 + () - "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. () -* 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. - - -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.  -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. - - -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  -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.  -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. + +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'. + +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  -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 - -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 - -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  -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. + +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), ... + ( ) -94x94-charset - GB2312(A), JISX0208(B), KSC5601(C), ... + `' is an attribute name such as `cn' for Common Name, `o' for +Organization, etc... -96x96-charset - none for the moment + `' 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 `(=*' 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. + +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: + +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 +(), 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. + +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: + +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.  -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. - -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 - -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 - -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. - -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;")) + => # - 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);") + => # - - 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;"))) + => # + + 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) + => # + + 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;")) + => # + (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;")) + => + (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;")) + => # + (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;")) + => # + (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;")) + => # + (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;")) + => # + (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;")) + => # + (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;")) + => # + (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');") + => # + (pq-cmd-status R) + => "INSERT 542086 1" + (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired' + WHERE shikona='Wakanohana';")) + => # + (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');")) + => # + (pq-cmd-tuples R) + => "1" + (setq R (pq-exec P "SELECT * from xemacs_test;")) + => # + (pq-cmd-tuples R) + => "" + (setq R (pq-exec P "DELETE FROM xemacs_test + WHERE shikona LIKE '%hana';")) + => # + (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');")) + => # + (pq-oid-value R) + => 542089 + (setq R (pq-exec P "SELECT shikona FROM xemacs_test + WHERE rank='Maegashira';")) + => # + (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.  -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 +------------------------------- - -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! # + 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: + # + 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) + => # + + 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;")) + => # + + - 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. diff --git a/info/lispref.info-42 b/info/lispref.info-42 index 4f7e2c4..333877f 100644 --- a/info/lispref.info-42 +++ b/info/lispref.info-42 @@ -50,1048 +50,1123 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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. - -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.  -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.  -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.  -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 - -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.  -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 + => # + + 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 + => # + + 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 + => (#) + + 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 + => (# # #) + + 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;")) + => # + (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 + => #  -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: - -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.  -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. + + +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::  -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 except following - another . (That is, it is ok to bind a sequence ending in - ` '.) - - The reason for this rule is that a non-prefix binding for 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.  -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 - -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'.  -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 (`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.  -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 - ;; Maintainer: Eric S. Raymond - ;; 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 - ;; Dave Sill - ;; Dave Brennan - ;; Eric Raymond + 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. + +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. + +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. + +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. + + +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.  -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. + + +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::. + + +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. + + +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. diff --git a/info/lispref.info-43 b/info/lispref.info-43 index aeb086b..144d591 100644 --- a/info/lispref.info-43 +++ b/info/lispref.info-43 @@ -50,1401 +50,1167 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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. - - -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.  -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'. - - -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::. - - -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.  -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.  -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' + +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' + +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' + +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' + +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' + +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' + +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' + +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!> | <8 | >8 | // + | < | > | == | <= | >= | != | de-sjis | en-sjis +ASSIGNMENT_OPERATOR := + += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>= +ARRAY := '[' integer ... ']' + + +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. + + +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. + + +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: CCL Examples, Prev: Calling CCL, Up: CCL + +CCL Examples +------------ + + This section is not yet written. + + +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. + + +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. + + +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 except following + another . (That is, it is ok to bind a sequence ending in + ` '.) + + The reason for this rule is that a non-prefix binding for 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. + + +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: 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. + + +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 (`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: 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 + ;; Maintainer: Eric S. Raymond + ;; 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 + ;; Dave Sill + ;; Dave Brennan + ;; Eric Raymond + +`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. + + +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. -* : 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. + + +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. diff --git a/info/xemacs-faq.info-3 b/info/xemacs-faq.info-3 index 39539b8..653e239 100644 --- a/info/xemacs-faq.info-3 +++ b/info/xemacs-faq.info-3 @@ -414,12 +414,12 @@ Q3.2.6: Can I have pixmap backgrounds in XEmacs? edit-faces'. -3.3: The Modeline -================= -  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? -------------------------------------------- diff --git a/info/xemacs-faq.info-5 b/info/xemacs-faq.info-5 index f5c6bcf..9007a77 100644 --- a/info/xemacs-faq.info-5 +++ b/info/xemacs-faq.info-5 @@ -755,6 +755,9 @@ Miscellaneous * 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) +  File: xemacs-faq.info, Node: Q6.0.1, Next: Q6.0.2, Prev: MS Windows, Up: MS Windows @@ -1085,7 +1088,7 @@ Could you briefly explain the differences between them?  -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? ----------------------------------------------------- @@ -1093,6 +1096,32 @@ Q6.3.3: What is the porting team doing at the moment? The porting team is continuing work on the MS Windows-specific code.  +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. + + File: xemacs-faq.info, Node: Current Events, Prev: MS Windows, Up: Top 7 What the Future Holds diff --git a/info/xemacs.info-10 b/info/xemacs.info-10 index 69739c6..f888910 100644 --- a/info/xemacs.info-10 +++ b/info/xemacs.info-10 @@ -30,6 +30,72 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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. + + File: xemacs.info, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode Outline Motion Commands @@ -1083,153 +1149,3 @@ a symbol, SYMBOL the value is a number, `C-M-q' need not recalculate indentation for the following lines until the end of the list. - -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 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, - just inserts a tab character in the buffer. Normally, this -variable is `nil', and 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. - diff --git a/info/xemacs.info-11 b/info/xemacs.info-11 index 67dc490..e6173be 100644 --- a/info/xemacs.info-11 +++ b/info/xemacs.info-11 @@ -30,6 +30,156 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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 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, + just inserts a tab character in the buffer. Normally, this +variable is `nil', and 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. + + File: xemacs.info, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs Automatic Display of Matching Parentheses @@ -1046,138 +1196,3 @@ To turn off this feature, set the variable `fortran-electric-line-number' to `nil'. Then inserting line numbers is like inserting anything else. - -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. - - -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. - - -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. - diff --git a/info/xemacs.info-12 b/info/xemacs.info-12 index 39e5227..644ad3c 100644 --- a/info/xemacs.info-12 +++ b/info/xemacs.info-12 @@ -30,6 +30,141 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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. + + +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. + + +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. + + File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran Columns @@ -1021,172 +1156,3 @@ it's best to exit XEmacs before upgrading an existing package. or changed packages. - -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. - - -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 '. - - 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. - - -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 '. - - 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. - diff --git a/info/xemacs.info-13 b/info/xemacs.info-13 index e14d1d6..11cb619 100644 --- a/info/xemacs.info-13 +++ b/info/xemacs.info-13 @@ -30,6 +30,175 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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. + + +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 '. + + 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. + + +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 '. + + 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. + + File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs Controlling Abbrev Expansion @@ -1058,190 +1227,3 @@ stores the previous point at the end of the mark ring. So, repeated use of this command moves point through all the old marks on the ring, one by one. - -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.) - - -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). - - -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 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. - diff --git a/info/xemacs.info-14 b/info/xemacs.info-14 index 0a7da91..828a37c 100644 --- a/info/xemacs.info-14 +++ b/info/xemacs.info-14 @@ -30,6 +30,193 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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.) + + +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). + + +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 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. + + File: xemacs.info, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary Times of Sunrise and Sunset @@ -937,274 +1124,3 @@ terminal. A similar normal hook, `today-invisible-calendar-hook' is run if the current date is _not_ visible in the window. - -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") ... ) - - -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)) - - -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. - - -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. - diff --git a/info/xemacs.info-15 b/info/xemacs.info-15 index bb5eb2c..cb56172 100644 --- a/info/xemacs.info-15 +++ b/info/xemacs.info-15 @@ -30,6 +30,277 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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") ... ) + + +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)) + + +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. + + +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. + + File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization Customizing the Diary @@ -930,246 +1201,3 @@ based on the value of the variable `lpr-switches'. Its value should be a list of strings, each string a switch starting with `-'. For example, the value could be `("-Pfoo")' to print on printer `foo'. - -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. - - -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. - - -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'. - - -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'. - - -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::. - - -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. - diff --git a/info/xemacs.info-16 b/info/xemacs.info-16 index 8f34089..d9f4b8b 100644 --- a/info/xemacs.info-16 +++ b/info/xemacs.info-16 @@ -30,6 +30,251 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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. + + +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. + + +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'. + + +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'. + + +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::. + + +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. + + File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization Minor Modes @@ -897,285 +1142,3 @@ letters and hyphens. before it can be executed. This is done to protect beginners from surprises. - -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 exits just - like . 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 '. - - * `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 . 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 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. - - -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 - - -File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding - -Changing Key Bindings Interactively -................................... - -`M-x global-set-key KEY CMD ' - Defines KEY globally to run CMD. - -`M-x local-set-key KEYS CMD ' - Defines KEY locally (in the major mode now in effect) to run CMD. - -`M-x local-unset-key KEYS ' - 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 C-f next-line - -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 C-x 4 $ spell-other-window - -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. - - -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 - (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 - ;;; in the keymap that is in force when you are running `dired'. - (define-key dired-mode-map '(meta control button3) 'my-command) - - -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 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 . 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 - diff --git a/info/xemacs.info-17 b/info/xemacs.info-17 index 24d4a3d..beafba4 100644 --- a/info/xemacs.info-17 +++ b/info/xemacs.info-17 @@ -30,6 +30,288 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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 exits just + like . 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 '. + + * `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 . 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 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. + + +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 + + +File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding + +Changing Key Bindings Interactively +................................... + +`M-x global-set-key KEY CMD ' + Defines KEY globally to run CMD. + +`M-x local-set-key KEYS CMD ' + Defines KEY locally (in the major mode now in effect) to run CMD. + +`M-x local-unset-key KEYS ' + 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 C-f next-line + +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 C-x 4 $ spell-other-window + +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. + + +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 + (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 + ;;; in the keymap that is in force when you are running `dired'. + (define-key dired-mode-map '(meta control button3) 'my-command) + + +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 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 . 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 + + File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings Disabling Commands @@ -603,7 +885,7 @@ kernel of Emacs uses. You type something other than `yes' or `no'  -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 ===== @@ -720,7 +1002,20 @@ argument is provided, the face is changed only in that frame; otherwise, it is changed in all frames.  -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. + + +File: xemacs.info, Node: X Resources, Prev: Frame Components, Up: Customization X Resources =========== @@ -985,301 +1280,3 @@ Resource List resources are used to initialize the variables `x-pointer-foreground-color' and `x-pointer-background-color'. - -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)'. - - -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'. - - -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. - - -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::. - - -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. - - -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::. - - -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. - - -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::. - diff --git a/info/xemacs.info-18 b/info/xemacs.info-18 index 406752e..f770b9b 100644 --- a/info/xemacs.info-18 +++ b/info/xemacs.info-18 @@ -30,6 +30,304 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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)'. + + +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'. + + +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. + + +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::. + + +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. + + +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::. + + +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. + + +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::. + + File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage Spontaneous Entry to Incremental Search @@ -294,785 +592,3 @@ net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous FTP server. It provides some introductory information and help for initial configuration problems. - -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 , - , or . *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 key and typing some other character; some have - special keys on the keyboard. , , , , and - 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 . - *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::. - - - The 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. - - - is a character used as a prefix for typing Meta characters on - keyboards lacking a key. Unlike the key (which, - like the key, is held down while another character is - typed), the 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 - or . 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::. - - - You can type at any time to ask what options you have, or - to ask what any command does. 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 , 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 key, you type a Control-Meta character by - typing 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 key held down. Such characters are given names that - start with `Meta-'. For example, `Meta-<' is typed by holding down - and at the same time typing `<' (which itself is done, on - most terminals, by holding down 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 - 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 , - 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::. - - - 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::. - diff --git a/info/xemacs.info-19 b/info/xemacs.info-19 index fd40504..a4fa596 100644 --- a/info/xemacs.info-19 +++ b/info/xemacs.info-19 @@ -30,945 +30,784 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -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. - - -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 , + , or . *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 key and typing some other character; some have + special keys on the keyboard. , , , , and + 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 . + *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::. + + + The 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. + + + is a character used as a prefix for typing Meta characters on + keyboards lacking a key. Unlike the key (which, + like the key, is held down while another character is + typed), the 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 + or . 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::. + + + You can type at any time to ask what options you have, or + to ask what any command does. 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 , 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 key, you type a Control-Meta character by + typing 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 key held down. Such characters are given names that + start with `Meta-'. For example, `Meta-<' is typed by holding down + and at the same time typing `<' (which itself is done, on + most terminals, by holding down 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 + 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 , + 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::. + + + 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::. diff --git a/info/xemacs.info-20 b/info/xemacs.info-20 index 8a6cac3..0711fc3 100644 --- a/info/xemacs.info-20 +++ b/info/xemacs.info-20 @@ -30,757 +30,953 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -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. + + +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. diff --git a/info/xemacs.info-21 b/info/xemacs.info-21 index 83f8068..fe387af 100644 --- a/info/xemacs.info-21 +++ b/info/xemacs.info-21 @@ -30,762 +30,765 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -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. - - -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. diff --git a/info/xemacs.info-5 b/info/xemacs.info-5 index 0761204..22cba33 100644 --- a/info/xemacs.info-5 +++ b/info/xemacs.info-5 @@ -30,6 +30,118 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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 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 (). + +`mouse-track-adjust' + Extend the existing selection. This is the default binding of + . + +`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 . + +`mouse-track-insert' + Make a selection with the mouse and insert it at point. This is + the default binding of . + +`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 () has been executed. + + The `M-x mouse-track-delete-and-insert' command is exactly the same +as the `mouse-track' command on , 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 , except that point is not moved; the +selected text is immediately inserted after being selected; and the +selection is immediately disowned afterwards. + + File: xemacs.info, Node: Killing, Next: Yanking, Prev: Additional Mouse Operations, Up: Top Deletion and Killing @@ -1131,60 +1243,3 @@ scrolling fast, regardless of `scroll-step'. To prevent this, set `scroll-conservatively' to a small value, which will have the result of overriding the redisplay preemption. - -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. - - -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. - diff --git a/info/xemacs.info-6 b/info/xemacs.info-6 index 3d51fe2..37d661e 100644 --- a/info/xemacs.info-6 +++ b/info/xemacs.info-6 @@ -30,6 +30,63 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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. + + +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. + + File: xemacs.info, Node: Display Vars, Prev: Selective Display, Up: Display Variables Controlling Display @@ -1090,85 +1147,3 @@ rename, and append to files, and operate on file directories. the files in it. * Misc File Ops:: Other things you can do on files. - -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 . 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 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. - diff --git a/info/xemacs.info-7 b/info/xemacs.info-7 index 2d2c1bb..8bda945 100644 --- a/info/xemacs.info-7 +++ b/info/xemacs.info-7 @@ -30,6 +30,88 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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 . 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 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. + + File: xemacs.info, Node: Visiting, Next: Saving, Prev: File Names, Up: Files Visiting Files @@ -991,118 +1073,3 @@ For example, if you merely fix some misspellings in comments, you can log the change with an entry beginning with `#' to avoid putting such trivia into `ChangeLog'. - -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 ' - 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 OLDVERS NEWVERS ' - 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 ' (`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'. - - -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. - - -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. - - -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. - diff --git a/info/xemacs.info-8 b/info/xemacs.info-8 index d409fd1..363f8d6 100644 --- a/info/xemacs.info-8 +++ b/info/xemacs.info-8 @@ -30,6 +30,121 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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 ' + 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 OLDVERS NEWVERS ' + 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 ' (`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'. + + +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. + + +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. + + +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. + + File: xemacs.info, Node: Making Snapshots, Next: Snapshot Caveats, Prev: Snapshots, Up: Snapshots Making and Using Snapshots @@ -1086,69 +1201,3 @@ Enhancement to GNU Emacs"). * Recognize Coding:: How XEmacs figures out which conversion to use. * Specify Coding:: Various ways to choose which conversion to use. - -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 ' is used for commands that pertain to -world scripts, coding systems, and input methods. - - -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 ' -(`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. - diff --git a/info/xemacs.info-9 b/info/xemacs.info-9 index 61e73e7..cbbf7d1 100644 --- a/info/xemacs.info-9 +++ b/info/xemacs.info-9 @@ -30,6 +30,72 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +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 ' is used for commands that pertain to +world scripts, coding systems, and input methods. + + +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 ' +(`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. + + File: xemacs.info, Node: Input Methods, Next: Select Input Method, Prev: Language Environments, Up: Mule Input Methods @@ -1072,69 +1138,3 @@ invisible. * Motion: Outline Motion. Special commands for moving through outlines. * Visibility: Outline Visibility. Commands to control what is visible. - -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. - -- 1.7.10.4